@shivaedev/work-fleet 0.0.0 → 0.1.1

package/src/providers/codexCloudConnection.ts

@@ -0,0 +1,49 @@
+import { Effect, Exit, type FileSystem, Redacted, Scope, Semaphore } from "effect";
+import type { ChildProcessSpawner } from "effect/process";
+import { type CodexLogin, codexAccessToken } from "#providers/codexLogin.ts";
+import { type CodexConnection, connect, failure, initialize, request } from "#providers/codexRpc.ts";
+
+function cloudUrl(endpoint: string) {
+	return Effect.try({ catch: () => failure("unavailable", "Invalid Codex Cloud endpoint"), try: () => new URL(endpoint) }).pipe(
+		Effect.filterOrFail(
+			(url) => url.protocol === "wss:" || (url.protocol === "ws:" && ["127.0.0.1", "localhost", "[::1]"].includes(url.hostname)),
+			() => failure("unavailable", "Codex Cloud bearer authentication requires a wss endpoint"),
+		),
+	);
+}
+// Connections reopen with a fresh login; a dropped socket fails in-flight mutations as ambiguous.
+export const codexCloudConnection = Effect.fn("CodexCloud.codexCloudConnection")(function* (endpoint: string, login: CodexLogin, timeoutMs: number) {
+	const url = yield* cloudUrl(endpoint);
+	const services = yield* Effect.context<FileSystem.FileSystem | ChildProcessSpawner.ChildProcessSpawner>();
+	const layerScope = yield* Effect.scope;
+	const lock = yield* Semaphore.make(1);
+	let current: { readonly connection: CodexConnection; readonly scope: Scope.Closeable } | undefined;
+	const open = Effect.gen(function* () {
+		if (current !== undefined) {
+			yield* Scope.close(current.scope, Exit.void);
+			current = undefined;
+		}
+		const token = yield* codexAccessToken(login, timeoutMs).pipe(Effect.provide(services));
+		const scope = yield* Scope.fork(layerScope);
+		const connection = yield* Effect.gen(function* () {
+			const opened = yield* connect(
+				{ protocols: ["codex-app-server", `codex-client.${crypto.randomUUID()}`, `openai-bearer.${Redacted.value(token)}`], url },
+				timeoutMs,
+			);
+			yield* initialize(opened, timeoutMs, true);
+			return opened;
+		}).pipe(
+			Scope.provide(scope),
+			Effect.onError(() => Scope.close(scope, Exit.void)),
+		);
+		current = { connection, scope };
+		return connection;
+	});
+	const connection = Semaphore.withPermits(
+		lock,
+		1,
+	)(Effect.suspend(() => (current !== undefined && !current.connection.closed.value ? Effect.succeed(current.connection) : open)));
+	return function rpc(method: string, params: unknown, mutation = false) {
+		return connection.pipe(Effect.flatMap((opened) => request(opened, timeoutMs, method, params, mutation)));
+	};
+});

package/src/providers/codexLocal.ts

@@ -0,0 +1,67 @@
+import { Context, Effect, Layer, Schema } from "effect";
+import { defineService } from "@shivaedev/effect-service/define-service.ts";
+import { codexAdapter } from "#providers/codexAdapter.ts";
+import { connect, failure, initialize, request } from "#providers/codexRpc.ts";
+import { SessionTransport } from "#session/service.ts";
+
+// The runtime owns execution; observer teardown only disconnects.
+export const CodexLocalConfiguration = Schema.Struct({ endpoint: Schema.String, requestTimeoutMs: Schema.Finite.check(Schema.isGreaterThan(0)) });
+export type CodexLocalConfiguration = typeof CodexLocalConfiguration.Type;
+
+function loopback(endpoint: string) {
+	return Effect.try({
+		catch: () => failure("unavailable", "Invalid local Codex endpoint"),
+		try: () => new URL(endpoint),
+	}).pipe(
+		Effect.filterOrFail(
+			(url) => url.protocol === "ws:" && ["127.0.0.1", "localhost", "[::1]"].includes(url.hostname) && url.username === "" && url.password === "",
+			() => failure("unavailable", "Local Codex requires an explicitly configured loopback WebSocket endpoint"),
+		),
+	);
+}
+export class CodexLocalConfig extends Context.Service<CodexLocalConfig, CodexLocalConfiguration>()("@shivaedev/work-fleet/CodexLocalConfig") {}
+
+// The installed CLI schema verifies these local methods; it provides no hosted transport contract.
+const CodexLocal = defineService({
+	id: "Fleet/CodexLocal",
+	initialize: Effect.gen(function* () {
+		const config = yield* Schema.decodeUnknownEffect(CodexLocalConfiguration)(yield* CodexLocalConfig).pipe(
+			Effect.mapError(() => failure("unavailable", "Local Codex configuration requires a finite positive request timeout")),
+		);
+		const url = yield* loopback(config.endpoint);
+		const connection = yield* connect({ url }, config.requestTimeoutMs);
+		yield* initialize(connection, config.requestTimeoutMs, false);
+		function rpc(method: string, params: unknown, mutation = false) {
+			return request(connection, config.requestTimeoutMs, method, params, mutation);
+		}
+		const resumed = new Set<string>();
+		return codexAdapter(rpc, {
+			beforeTurn: (input) =>
+				(resumed.has(input.sessionId)
+					? Effect.succeed({})
+					: rpc("thread/resume", { excludeTurns: true, threadId: input.sessionId }).pipe(
+							Effect.tap(() => Effect.sync(() => resumed.add(input.sessionId))),
+							Effect.as({}),
+						)
+				).pipe(
+					Effect.map((params) =>
+						input.access === "read-only" ? { ...params, approvalPolicy: "never", sandboxPolicy: { networkAccess: true, type: "readOnly" } } : params,
+					),
+				),
+			provisioning: "ready",
+			sessionStarted: (sessionId) => resumed.add(sessionId),
+			threadStart: (input) => ({
+				...(input.access === "read-only"
+					? { approvalPolicy: "never", config: { "sandbox_read_only.network_access": true }, sandbox: "read-only" }
+					: {}),
+				cwd: input.cwd,
+				ephemeral: false,
+				...(input.settings?.model === undefined ? {} : { model: input.settings.model }),
+				...(input.settings?.serviceTier === undefined ? {} : { serviceTier: input.settings.serviceTier }),
+			}),
+		});
+	}),
+	methods: (adapter) => adapter,
+	requires: [CodexLocalConfig],
+});
+export const codexLocalLayer = Layer.effect(SessionTransport)(CodexLocal).pipe(Layer.provide(CodexLocal.layer));

package/src/providers/codexLogin.ts

@@ -0,0 +1,87 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { Clock, Config, Effect, FileSystem, Option, Redacted, Schema, Stream } from "effect";
+import { ChildProcess, ChildProcessSpawner } from "effect/process";
+import { NAME, TITLE, VERSION } from "#packageInfo.ts";
+import { failure } from "#providers/codexRpc.ts";
+
+export interface CodexLogin {
+	readonly authFile?: string | undefined;
+	readonly refreshCommand?: { readonly command: string; readonly args: readonly string[] } | undefined;
+}
+const AuthFile = Schema.Struct({
+	tokens: Schema.Struct({ accessToken: Schema.String, accountId: Schema.optional(Schema.NullOr(Schema.String)) }).pipe(
+		Schema.encodeKeys({ accessToken: "access_token", accountId: "account_id" }),
+	),
+});
+const Claims = Schema.Struct({ exp: Schema.Finite });
+const RefreshReply = Schema.Struct({ error: Schema.optional(Schema.Unknown), id: Schema.Literal(2) });
+// A token that expires within this window could lapse during the handshake.
+const EXPIRY_SKEW_MS = 5 * 60 * 1000;
+function unreadable() {
+	return failure("unavailable", "Codex login token is unreadable; sign in with the Codex CLI");
+}
+
+const authFilePath = Effect.fn("CodexLogin.authFilePath")(function* (login: CodexLogin) {
+	if (login.authFile !== undefined) {
+		return login.authFile;
+	}
+	const home = yield* Config.option(Config.String("CODEX_HOME")).pipe(Effect.orElseSucceed(() => Option.none<string>()));
+	return join(
+		Option.getOrElse(home, () => join(homedir(), ".codex")),
+		"auth.json",
+	);
+});
+const readToken = Effect.fn("CodexLogin.readToken")(function* (authFile: string) {
+	const fs = yield* FileSystem.FileSystem;
+	const content = yield* fs.readFileString(authFile).pipe(Effect.mapError(() => failure("unavailable", "Codex login file is unavailable")));
+	const auth = yield* Schema.decodeUnknownEffect(Schema.fromJsonString(AuthFile))(content).pipe(
+		Effect.mapError(() => failure("unavailable", "Codex login file has no ChatGPT access token; sign in with the Codex CLI")),
+	);
+	const payload = yield* Effect.try({
+		catch: unreadable,
+		try: () => Buffer.from(auth.tokens.accessToken.split(".")[1] ?? "", "base64url").toString("utf8"),
+	});
+	const claims = yield* Schema.decodeUnknownEffect(Schema.fromJsonString(Claims))(payload).pipe(Effect.mapError(unreadable));
+	return { accountId: auth.tokens.accountId ?? undefined, expiresAt: claims.exp * 1000, token: Redacted.make(auth.tokens.accessToken) };
+});
+// The Codex CLI owns the login file and its refresh-token rotation; Fleet only asks it to refresh.
+const refreshLogin = Effect.fn("CodexLogin.refreshLogin")(function* (command: NonNullable<CodexLogin["refreshCommand"]>) {
+	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+	const messages = [
+		{ id: 1, method: "initialize", params: { capabilities: null, clientInfo: { name: NAME, title: TITLE, version: VERSION } } },
+		{ method: "initialized" },
+		{ id: 2, method: "account/read", params: { refreshToken: true } },
+	];
+	const stdin = Stream.make(new TextEncoder().encode(messages.map((message) => `${JSON.stringify(message)}\n`).join(""))).pipe(
+		Stream.concat(Stream.never),
+	);
+	const reply = yield* spawner.streamLines(ChildProcess.make(command.command, [...command.args], { stdin })).pipe(
+		Stream.filterMap((line) => Schema.decodeUnknownResult(Schema.fromJsonString(RefreshReply))(line)),
+		Stream.runHead,
+		Effect.mapError(() => failure("unavailable", "Codex CLI could not refresh the login")),
+	);
+	if (Option.isNone(reply) || reply.value.error !== undefined) {
+		return yield* Effect.fail(failure("unavailable", "Codex CLI could not refresh the login; sign in with the Codex CLI"));
+	}
+});
+export const codexCredentials = Effect.fn("CodexLogin.codexCredentials")(function* (login: CodexLogin, timeoutMs: number) {
+	const authFile = yield* authFilePath(login);
+	const current = yield* readToken(authFile);
+	if (current.expiresAt - EXPIRY_SKEW_MS > (yield* Clock.currentTimeMillis)) {
+		return current;
+	}
+	yield* refreshLogin(login.refreshCommand ?? { args: ["app-server", "--listen", "stdio://"], command: "codex" }).pipe(
+		Effect.timeout(`${timeoutMs} millis`),
+		Effect.catchTag("TimeoutError", () => Effect.fail(failure("unavailable", "Codex CLI login refresh timed out"))),
+	);
+	const refreshed = yield* readToken(authFile);
+	if (refreshed.expiresAt - EXPIRY_SKEW_MS <= (yield* Clock.currentTimeMillis)) {
+		return yield* Effect.fail(failure("unavailable", "Codex login is expired; sign in with the Codex CLI"));
+	}
+	return refreshed;
+});
+
+export const codexAccessToken = Effect.fn("CodexLogin.codexAccessToken")((login: CodexLogin, timeoutMs: number) =>
+	codexCredentials(login, timeoutMs).pipe(Effect.map((credentials) => credentials.token)),
+);

package/src/providers/codexProtocol.ts

@@ -0,0 +1,33 @@
+import { Schema } from "effect";
+
+const Echo = Schema.optional(Schema.NullOr(Schema.String));
+export const ThreadResponse = Schema.Struct({
+	model: Echo,
+	reasoningEffort: Echo,
+	serviceTier: Echo,
+	thread: Schema.Struct({ id: Schema.String }),
+});
+export const TurnResponse = Schema.Struct({ turn: Schema.Struct({ id: Schema.String }) });
+export const Item = Schema.Struct({
+	changes: Schema.optional(Schema.Unknown),
+	clientId: Schema.optional(Schema.NullOr(Schema.String)),
+	id: Schema.String,
+	phase: Schema.optional(Schema.NullOr(Schema.String)),
+	status: Schema.optional(Schema.String),
+	text: Schema.optional(Schema.String),
+	type: Schema.String,
+});
+export const Turn = Schema.Struct({
+	error: Schema.optional(Schema.NullOr(Schema.Struct({ codexErrorInfo: Schema.optional(Schema.Unknown), message: Schema.String }))),
+	id: Schema.String,
+	items: Schema.Array(Item),
+	status: Schema.Literals(["inProgress", "completed", "interrupted", "failed"]),
+});
+export const TurnsResponse = Schema.Struct({ data: Schema.Array(Turn), nextCursor: Schema.NullOr(Schema.String) });
+export const ItemsResponse = Schema.Struct({ data: Schema.Array(Schema.Struct({ item: Item })), nextCursor: Schema.NullOr(Schema.String) });
+export const Envelope = Schema.Struct({
+	error: Schema.optional(Schema.Unknown),
+	id: Schema.optional(Schema.Union([Schema.String, Schema.Number])),
+	method: Schema.optional(Schema.String),
+	result: Schema.optional(Schema.Unknown),
+});

package/src/providers/codexReportAttachments.ts

@@ -0,0 +1,23 @@
+import { Effect } from "effect";
+import { reportFileChanges } from "#host/reportFileChanges.ts";
+import { CODEX_CLOUD_ENDPOINT } from "#providers/codexCloud.ts";
+import { codexCloudConnection } from "#providers/codexCloudConnection.ts";
+import type { CodexLogin } from "#providers/codexLogin.ts";
+import { type CodexRequest, codexTurns } from "#providers/codexTurns.ts";
+import { REPORT_LIMITS } from "#reportLimits.ts";
+import type { SessionObservation } from "#session/schema.ts";
+
+export function makeCodexReportAttachments(rpc: CodexRequest) {
+	const { readItems } = codexTurns(rpc);
+	return (observation: SessionObservation) =>
+		readItems(observation.receipt, REPORT_LIMITS.downloadBytes).pipe(Effect.flatMap((items) => reportFileChanges(items, observation.output)));
+}
+export function codexReportAttachments(login: CodexLogin & { readonly endpoint?: string | undefined }, timeoutMs: number) {
+	return (observation: SessionObservation) =>
+		Effect.scoped(
+			Effect.gen(function* () {
+				const rpc = yield* codexCloudConnection(login.endpoint ?? CODEX_CLOUD_ENDPOINT, login, timeoutMs);
+				return yield* makeCodexReportAttachments(rpc)(observation);
+			}),
+		);
+}

package/src/providers/codexRpc.ts

@@ -0,0 +1,140 @@
+import { Effect, Schedule, Schema } from "effect";
+import { NAME, TITLE, VERSION } from "#packageInfo.ts";
+import { capacity } from "#providers/capacity.ts";
+import { Envelope } from "#providers/codexProtocol.ts";
+import { genericRejection } from "#providers/genericRejection.ts";
+import { SessionFailure } from "#session/schema.ts";
+
+type Resume = (result: Effect.Effect<unknown, SessionFailure>) => void;
+const RpcError = Schema.Struct({ code: Schema.optional(Schema.Number), message: Schema.String });
+function rejection(error: unknown) {
+	const decoded = Schema.decodeUnknownOption(RpcError)(error);
+	return new SessionFailure({
+		capacity: capacity(error),
+		code: decoded._tag === "Some" && decoded.value.code === -32_001 ? "session-queue-full" : "session-rejected",
+		message:
+			decoded._tag === "Some" ? `Codex rejected the protocol request: ${decoded.value.message.slice(0, 500)}` : "Codex rejected the protocol request",
+		reason: "rejected",
+	});
+}
+export interface CodexConnection {
+	readonly closed: {
+		value: boolean;
+	};
+	readonly nextId: {
+		value: number;
+	};
+	readonly pending: Map<number, Resume>;
+	readonly socket: WebSocket;
+}
+export function failure(reason: SessionFailure["reason"], message: string) {
+	return new SessionFailure({ message, reason });
+}
+function failPending(connection: CodexConnection, error: SessionFailure) {
+	for (const pending of connection.pending.values()) {
+		pending(Effect.fail(error));
+	}
+	connection.pending.clear();
+}
+export interface CodexEndpoint {
+	readonly protocols?: readonly string[];
+	readonly url: URL;
+}
+function openSocket(endpoint: CodexEndpoint) {
+	return Effect.callback<CodexConnection, SessionFailure>((resume) => {
+		let socket: WebSocket;
+		try {
+			socket = new WebSocket(endpoint.url, endpoint.protocols === undefined ? undefined : [...endpoint.protocols]);
+		} catch {
+			resume(Effect.fail(failure("unavailable", "Invalid Codex endpoint")));
+			return;
+		}
+		const connection: CodexConnection = { closed: { value: false }, nextId: { value: 0 }, pending: new Map(), socket };
+		function disconnected() {
+			connection.closed.value = true;
+			for (const pending of connection.pending.values()) {
+				pending(
+					Effect.fail(
+						new SessionFailure({
+							code: "session-unavailable",
+							message: "Codex disconnected; reconcile persisted submission before retrying",
+							reason: "ambiguous",
+						}),
+					),
+				);
+			}
+			connection.pending.clear();
+		}
+		socket.addEventListener("close", disconnected);
+		socket.addEventListener("error", () => {
+			disconnected();
+			resume(Effect.fail(failure("unavailable", "Could not connect to the configured Codex endpoint")));
+		});
+		socket.addEventListener("open", () => resume(Effect.succeed(connection)), { once: true });
+		socket.addEventListener("message", (event) => {
+			try {
+				const envelope = Schema.decodeUnknownSync(Envelope)(JSON.parse(String(event.data)));
+				if (envelope.method !== undefined && envelope.id !== undefined) {
+					// A provider request cannot grant itself execution or delivery authority.
+					socket.send(JSON.stringify({ error: { code: -32_601, message: "Fleet transport has no approval handler" }, id: envelope.id }));
+					return;
+				}
+				if (typeof envelope.id !== "number") {
+					return;
+				}
+				const pending = connection.pending.get(envelope.id);
+				connection.pending.delete(envelope.id);
+				pending?.(envelope.error === undefined ? Effect.succeed(envelope.result) : Effect.fail(rejection(envelope.error)));
+			} catch {
+				failPending(connection, failure("protocol", "Codex returned an invalid protocol envelope"));
+			}
+		});
+		return Effect.sync(() => socket.close());
+	});
+}
+export function connect(endpoint: CodexEndpoint, timeoutMs: number) {
+	return Effect.acquireRelease(
+		openSocket(endpoint).pipe(
+			Effect.timeout(`${timeoutMs} millis`),
+			Effect.catchTag("TimeoutError", () => Effect.fail(failure("unavailable", "Codex connection timed out"))),
+		),
+		(connection) => Effect.sync(() => connection.socket.close()),
+	);
+}
+export function initialize(connection: CodexConnection, timeoutMs: number, experimentalApi: boolean) {
+	return request(connection, timeoutMs, "initialize", {
+		capabilities: experimentalApi ? { experimentalApi } : null,
+		clientInfo: { name: NAME, title: TITLE, version: VERSION },
+	}).pipe(Effect.andThen(Effect.sync(() => connection.socket.send(JSON.stringify({ method: "initialized" })))));
+}
+export function request(connection: CodexConnection, timeoutMs: number, method: string, params: unknown, mutation = false) {
+	return Effect.callback<unknown, SessionFailure>((resume) => {
+		if (connection.closed.value) {
+			resume(Effect.fail(failure("unavailable", "Codex connection is closed")));
+			return;
+		}
+		connection.nextId.value += 1;
+		const id = connection.nextId.value;
+		connection.pending.set(id, resume);
+		try {
+			connection.socket.send(JSON.stringify({ id, method, params }));
+		} catch {
+			connection.pending.delete(id);
+			resume(Effect.fail(failure(mutation ? "ambiguous" : "unavailable", "Codex write failed")));
+		}
+		return Effect.sync(() => {
+			connection.pending.delete(id);
+		});
+	}).pipe(
+		Effect.timeout(`${timeoutMs} millis`),
+		Effect.catchTag("TimeoutError", () =>
+			Effect.fail(failure(mutation ? "ambiguous" : "unavailable", "Codex request timed out; preserve submission ownership")),
+		),
+		Effect.retry({ schedule: Schedule.exponential("30 seconds"), times: 2, while: genericRejection }),
+	);
+}
+export function decode<A, TEncoded>(schema: Schema.Codec<A, TEncoded>, value: unknown) {
+	return Schema.decodeUnknownEffect(schema)(value).pipe(
+		Effect.mapError(() => failure("protocol", "Codex returned an incompatible protocol response")),
+	);
+}

package/src/providers/codexSettings.ts

@@ -0,0 +1,31 @@
+import { Effect } from "effect";
+import type { ThreadResponse } from "#providers/codexProtocol.ts";
+import { failure } from "#providers/codexRpc.ts";
+import type { LaunchSettings } from "#session/schema.ts";
+
+export function settingsParams(settings: LaunchSettings | undefined) {
+	return {
+		...(settings?.model === undefined ? {} : { model: settings.model }),
+		...(settings?.effort === undefined ? {} : { effort: settings.effort }),
+		...(settings?.serviceTier === undefined ? {} : { serviceTier: settings.serviceTier }),
+	};
+}
+// A provider that normalizes or ignores a requested setting must not run work with its own default.
+export const echoedSettings = Effect.fn("Codex.echoedSettings")(function* (
+	requested: LaunchSettings | undefined,
+	response: typeof ThreadResponse.Type,
+) {
+	const pairs = [
+		["model", requested?.model, response.model],
+		["reasoning effort", requested?.effort, response.reasoningEffort],
+		["service tier", requested?.serviceTier, response.serviceTier],
+	] as const;
+	for (const [name, wanted, actual] of pairs) {
+		if (wanted !== undefined && actual !== undefined && actual !== wanted) {
+			return yield* Effect.fail(failure("rejected", `Codex started the thread with ${name} ${actual ?? "unset"} instead of ${wanted}`));
+		}
+	}
+	yield* Effect.logInfo("Codex thread started").pipe(
+		Effect.annotateLogs({ model: response.model, reasoningEffort: response.reasoningEffort, serviceTier: response.serviceTier }),
+	);
+});

package/src/providers/codexTurns.ts

@@ -0,0 +1,133 @@
+import { Effect } from "effect";
+import { type Item, ItemsResponse, type Turn, TurnsResponse } from "#providers/codexProtocol.ts";
+import { decode, failure } from "#providers/codexRpc.ts";
+import { makeWaitUntilIdle } from "#providers/makeWaitUntilIdle.ts";
+import { readActiveTurn } from "#providers/readActiveTurn.ts";
+import { reportLimit } from "#reportLimits.ts";
+import { SessionFailure, type SessionReceipt } from "#session/schema.ts";
+
+export type CodexRequest = (method: string, params: unknown, mutation?: boolean) => Effect.Effect<unknown, SessionFailure>;
+function finalOutput(items: readonly (typeof Item.Type)[]) {
+	const messages = items.filter((item) => item.type === "agentMessage" && item.text !== undefined);
+	const final = messages.filter((item) => item.phase === "final_answer");
+	return (final.length > 0 ? final : messages).map((item) => item.text).join("\n");
+}
+function rememberCursor(cursors: Set<string>, cursor: string | null, message = "Codex repeated an item pagination cursor") {
+	if (cursor === null) {
+		return Effect.void;
+	}
+	if (cursors.has(cursor)) {
+		return Effect.fail(failure("protocol", message));
+	}
+	cursors.add(cursor);
+	return Effect.void;
+}
+export function codexTurns(rpc: CodexRequest) {
+	function turns(sessionId: string, cursor: string | null, full: boolean) {
+		return rpc("thread/turns/list", {
+			cursor,
+			itemsView: full ? "full" : "notLoaded",
+			limit: 100,
+			sortDirection: "desc",
+			threadId: sessionId,
+		}).pipe(Effect.flatMap((value) => decode(TurnsResponse, value)));
+	}
+	const readTurn = Effect.fn("Codex.readTurn")(function* (sessionId: string, turnId: string, full = false) {
+		let cursor: string | null = null;
+		const cursors = new Set<string>();
+		const progress: { id: string; status?: string | undefined }[] = [];
+		do {
+			const page: typeof TurnsResponse.Type = yield* turns(sessionId, cursor, full);
+			const found = page.data.find((turn) => turn.id === turnId);
+			if (found !== undefined) {
+				return { progress, turn: found };
+			}
+			for (const turn of page.data.filter((entry) => entry.status === "inProgress")) {
+				progress.push({ id: turn.id, status: turn.status });
+				progress.push(...turn.items.map(({ id, status }) => ({ id: `${turn.id}/${id}`, status })));
+			}
+			cursor = page.nextCursor;
+			yield* rememberCursor(cursors, cursor, "Codex repeated a turn pagination cursor");
+		} while (cursor !== null);
+		return { progress, turn: undefined };
+	});
+	const findTurn = Effect.fn("Codex.findTurn")(function* (sessionId: string, turnId: string, full = false) {
+		const { turn } = yield* readTurn(sessionId, turnId, full);
+		return (
+			turn
+			?? (yield* new SessionFailure({
+				code: "session-turn-missing",
+				message: "The acknowledged Codex turn is not observable",
+				reason: "ambiguous",
+			}))
+		);
+	});
+	const waitUntilIdle = makeWaitUntilIdle((sessionId, cursor) => turns(sessionId, cursor, false));
+	const operationTurn = Effect.fn("Codex.operationTurn")(function* (sessionId: string, operationId: string) {
+		let cursor: string | null = null;
+		const matching: (typeof Turn.Type)[] = [];
+		const cursors = new Set<string>();
+		let empty = true;
+		let idle = true;
+		do {
+			const page: typeof TurnsResponse.Type = yield* turns(sessionId, cursor, true);
+			empty = empty && page.data.length === 0;
+			idle = idle && page.data.every((turn) => turn.status === "completed" || turn.status === "failed" || turn.status === "interrupted");
+			matching.push(...page.data.filter((turn) => turn.items.some((item) => item.type === "userMessage" && item.clientId === operationId)));
+			cursor = page.nextCursor;
+			yield* rememberCursor(cursors, cursor, "Codex repeated a turn pagination cursor");
+		} while (cursor !== null);
+		if (matching.length > 1) {
+			return yield* Effect.fail(
+				new SessionFailure({
+					code: "duplicate-turns",
+					message: "Multiple Codex turns match one operation; retain reservation",
+					reason: "ambiguous",
+					...(matching.every((turn) => turn.status !== "inProgress")
+						? { terminalReceipts: matching.map((turn) => ({ sessionId, turnId: turn.id })) }
+						: {}),
+				}),
+			);
+		}
+		const turnId = matching[0]?.id;
+		return { empty, idle, turnId };
+	});
+	const readItems = Effect.fn("Codex.readItems")(function* (receipt: SessionReceipt, byteLimit?: number) {
+		let cursor: string | null = null;
+		const items: (typeof Item.Type)[] = [];
+		const cursors = new Set<string>();
+		let bytes = 0;
+		do {
+			const response: unknown = yield* rpc("thread/items/list", {
+				cursor,
+				limit: 100,
+				sortDirection: "asc",
+				threadId: receipt.sessionId,
+				turnId: receipt.turnId,
+			});
+			bytes += Buffer.byteLength(JSON.stringify(response) ?? "null", "utf8");
+			if (byteLimit !== undefined && bytes > byteLimit) {
+				return yield* Effect.fail(failure("protocol", reportLimit("downloadBytes").message));
+			}
+			const page: typeof ItemsResponse.Type = yield* decode(ItemsResponse, response);
+			for (const { item } of page.data) {
+				items.push(item);
+			}
+			cursor = page.nextCursor;
+			yield* rememberCursor(cursors, cursor);
+		} while (cursor !== null);
+		return items;
+	});
+	function readOutput(receipt: SessionReceipt) {
+		return readItems(receipt).pipe(Effect.map(finalOutput));
+	}
+	return {
+		findTurn,
+		hasActiveTurn: readActiveTurn((sessionId, cursor) => turns(sessionId, cursor, false)),
+		operationTurn,
+		readItems,
+		readOutput,
+		readTurn,
+		waitUntilIdle,
+	};
+}

package/src/providers/genericRejection.ts

@@ -0,0 +1,12 @@
+import type { SessionFailure } from "#session/schema.ts";
+
+export function genericRejection(error: SessionFailure) {
+	return (
+		error.reason === "rejected"
+		&& error.code === "session-rejected"
+		&& error.capacity === undefined
+		&& /^Codex rejected the protocol request(?::\s*(?:(?:Something went wrong|Internal (?:server )?error)\.?)?(?:\s+Request ID:\s*\S+)?)?$/iu.test(
+			error.message,
+		)
+	);
+}

package/src/providers/makeWaitUntilIdle.ts

@@ -0,0 +1,30 @@
+import { Clock, Effect } from "effect";
+import { type ReadTurnPage, readActiveTurn } from "#providers/readActiveTurn.ts";
+
+export function makeWaitUntilIdle(readPage: ReadTurnPage) {
+	const hasActiveTurn = readActiveTurn(readPage);
+	const poll = Effect.fn("Codex.poll")(function* (sessionId: string, deadline: number) {
+		let delay = 2000;
+		while ((yield* Clock.currentTimeMillis) < deadline) {
+			if (!(yield* hasActiveTurn(sessionId))) {
+				return (yield* Clock.currentTimeMillis) < deadline;
+			}
+			const remaining = deadline - (yield* Clock.currentTimeMillis);
+			if (remaining <= 0) {
+				return false;
+			}
+			yield* Effect.sleep(Math.min(delay, remaining));
+			delay = Math.min(30_000, delay * 2);
+		}
+		return false;
+	});
+	return Effect.fn("Codex.waitUntilIdle")(function* (sessionId: string, deadline: number) {
+		const remaining = deadline - (yield* Clock.currentTimeMillis);
+		return remaining <= 0
+			? false
+			: yield* poll(sessionId, deadline).pipe(
+					Effect.timeout(`${remaining} millis`),
+					Effect.catchTag("TimeoutError", () => Effect.succeed(false)),
+				);
+	});
+}

package/src/providers/observeCodexTurn.ts

@@ -0,0 +1,40 @@
+import { Effect, Schema } from "effect";
+import type { codexTurns } from "#providers/codexTurns.ts";
+import { ProviderCapacity, type SessionObservation, type SessionReceipt } from "#session/schema.ts";
+
+export function observeCodexTurn(turns: ReturnType<typeof codexTurns>, provisioning: SessionObservation["provisioning"]) {
+	const terminal = new Map<string, SessionObservation>();
+	return Effect.fn("Codex.observe")(function* (receipt: SessionReceipt) {
+		const key = `${receipt.sessionId}/${receipt.turnId}`;
+		const cached = terminal.get(key);
+		if (cached !== undefined) {
+			return cached;
+		}
+		const { turn, progress } = yield* turns.readTurn(receipt.sessionId, receipt.turnId, true);
+		if (turn === undefined) {
+			return {
+				execution: "accepted" as const,
+				output: "",
+				progress: progress.sort((left, right) => left.id.localeCompare(right.id)),
+				provisioning,
+				receipt,
+				turnMissing: true,
+			};
+		}
+		const output = turn.status === "inProgress" ? "" : yield* turns.readOutput(receipt);
+		const capacity = Schema.decodeUnknownOption(ProviderCapacity)(turn.error?.codexErrorInfo);
+		const observation: SessionObservation = {
+			capacity: capacity._tag === "Some" && turn.status === "failed" ? capacity.value : undefined,
+			error: turn.error?.message,
+			execution: turn.status === "inProgress" ? "running" : turn.status,
+			output,
+			progress: turn.items.map(({ id, status }) => ({ id, status })).sort((left, right) => left.id.localeCompare(right.id)),
+			provisioning,
+			receipt,
+		};
+		if (observation.execution !== "running") {
+			terminal.set(key, observation);
+		}
+		return observation;
+	});
+}