Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.
import { createCodexRuntimeApprovals } from "./codex/CodexRuntimeApprovals.ts";
import { createCodexNotifications } from "./codex/CodexNotifications.ts";
import { createCodexServerRequests } from "./codex/CodexServerRequests.ts";
import {
ApprovalRequestId,
EventId,
type ProviderEvent,
type ProviderSession,
type ProviderTurnStartResult,
TurnId,
} from "@akeru/contracts";
import { resolveSpawnCommand } from "@akeru/shared/shell";
import * as Crypto from "effect/Crypto";
import * as DateTime from "effect/DateTime";
import * as Effect from "effect/Effect";
import * as Exit from "effect/Exit";
import * as Layer from "effect/Layer";
import * as Path from "effect/Path";
import * as Queue from "effect/Queue";
import * as Ref from "effect/Ref";
import * as Scope from "effect/Scope";
import * as Stream from "effect/Stream";
import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
import * as CodexClient from "effect-codex-app-server/client";
import * as CodexErrors from "effect-codex-app-server/errors";
import * as CodexRpc from "effect-codex-app-server/rpc";
import { buildCodexInitializeParams } from "./codex/CodexCapabilitiesProbe.ts";
import { codexSessionAppServerArgs } from "./codexLaunchArgs.ts";
import { expandHomePath } from "../../pathExpansion.ts";
import {
decodeV2TurnStartResponse,
hasConfiguredMcpServer,
normalizeCodexModelSlug,
buildTurnStartParams,
} from "./codex/CodexRuntimeRequests.ts";
import {
PROVIDER,
type CodexSessionRuntimeOptions,
type CodexSessionRuntimeShape,
type PendingApproval,
type ApprovalCorrelation,
type PendingUserInput,
} from "./codex/CodexRuntimeState.ts";
import {
CODEX_APP_SERVER_FORCE_KILL_AFTER,
readResumeCursorThreadId,
classifyCodexStderrLine,
openCodexThread,
} from "./codex/CodexRuntimeOpening.ts";
import { CodexSessionRuntimeThreadIdMissingError } from "./codex/CodexRuntimeErrors.ts";
import {
type CodexServerNotification,
codexServerNotification,
memoryConsolidationNotificationFilter,
type CollabChildAgentState,
} from "./codex/CodexRuntimeNotifications.ts";
import {
currentProviderThreadId,
updateSession,
parseThreadSnapshot,
} from "./codex/CodexRuntimeSessions.ts";
export const makeCodexSessionRuntime = (
options: CodexSessionRuntimeOptions,
): Effect.Effect<
CodexSessionRuntimeShape,
CodexErrors.CodexAppServerError,
ChildProcessSpawner.ChildProcessSpawner | Crypto.Crypto | Scope.Scope | Path.Path
> =>
Effect.gen(function* () {
const path = yield* Path.Path;
const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
const runtimeScope = yield* Scope.Scope;
const crypto = yield* Crypto.Crypto;
const events = yield* Queue.unbounded<ProviderEvent>();
const pendingApprovalsRef = yield* Ref.make(new Map<ApprovalRequestId, PendingApproval>());
const approvalCorrelationsRef = yield* Ref.make(new Map<string, ApprovalCorrelation>());
const pendingUserInputsRef = yield* Ref.make(new Map<ApprovalRequestId, PendingUserInput>());
const collabReceiverTurnsRef = yield* Ref.make(new Map<string, TurnId>());
const collabChildAgentsRef = yield* Ref.make(new Map<string, CollabChildAgentState>());
/** Child provider-thread id → its currently running provider turn id. */
const collabChildLiveTurnsRef = yield* Ref.make(new Map<string, string>());
const suppressMemoryConsolidationNotification = memoryConsolidationNotificationFilter();
const closedRef = yield* Ref.make(false);
// `~` is not shell-expanded when env vars are set via
// `child_process.spawn`; `expandHomePath` lets a configured
// `CODEX_HOME=~/.codex_work` reach codex as an absolute path.
const resolvedHomePath = options.homePath ? expandHomePath(options.homePath, path) : undefined;
const env = {
...options.environment,
...(resolvedHomePath ? { CODEX_HOME: resolvedHomePath } : {}),
};
const extendEnv = options.environment === undefined;
const appServerArgs = codexSessionAppServerArgs(options.appServerArgs, options.launchArgs);
const spawnCommand = yield* resolveSpawnCommand(options.binaryPath, appServerArgs, {
env,
extendEnv,
});
const child = yield* spawner
.spawn(
ChildProcess.make(spawnCommand.command, spawnCommand.args, {
cwd: options.cwd,
env,
extendEnv,
forceKillAfter: CODEX_APP_SERVER_FORCE_KILL_AFTER,
shell: spawnCommand.shell,
}),
)
.pipe(
Effect.provideService(Scope.Scope, runtimeScope),
Effect.mapError(
(cause) =>
new CodexErrors.CodexAppServerSpawnError({
command: `${options.binaryPath} app-server`,
cause,
}),
),
);
const clientContext = yield* CodexClient.layerChildProcess(child).pipe(
Layer.build,
Effect.provideService(Scope.Scope, runtimeScope),
);
const client = yield* Effect.service(CodexClient.CodexAppServerClient).pipe(
Effect.provide(clientContext),
);
const serverNotifications = yield* Queue.unbounded<CodexServerNotification>();
const nowIso = Effect.map(DateTime.now, DateTime.formatIso);
const randomUUIDv4 = (purpose: CodexErrors.CodexAppServerIdentifierPurpose) =>
crypto.randomUUIDv4.pipe(
Effect.mapError(
(cause) =>
new CodexErrors.CodexAppServerIdentifierGenerationError({
purpose,
cause,
}),
),
);
const sessionCreatedAt = yield* nowIso;
const initialSession = {
provider: PROVIDER,
...(options.providerInstanceId ? { providerInstanceId: options.providerInstanceId } : {}),
status: "connecting",
runtimeMode: options.runtimeMode,
cwd: options.cwd,
...(options.model ? { model: options.model } : {}),
threadId: options.threadId,
...(options.resumeCursor !== undefined ? { resumeCursor: options.resumeCursor } : {}),
createdAt: sessionCreatedAt,
updatedAt: sessionCreatedAt,
} satisfies ProviderSession;
const sessionRef = yield* Ref.make<ProviderSession>(initialSession);
const offerEvent = (event: ProviderEvent) => Queue.offer(events, event).pipe(Effect.asVoid);
const emitEvent = (event: Omit<ProviderEvent, "id" | "provider" | "createdAt">) =>
Effect.gen(function* () {
const id = yield* randomUUIDv4("provider-event");
return yield* offerEvent({
id: EventId.make(id),
provider: PROVIDER,
...(options.providerInstanceId ? { providerInstanceId: options.providerInstanceId } : {}),
createdAt: yield* nowIso,
...event,
});
});
const emitSessionEvent = (method: string, message: string) =>
emitEvent({
kind: "session",
threadId: options.threadId,
method,
message,
});
const { settlePendingApprovals, settlePendingUserInputs } = createCodexRuntimeApprovals({
pendingApprovalsRef,
pendingUserInputsRef,
});
/**
* Registers v2 collab children and re-emits their notifications as
* synthetic `collabAgent/*` events for the adapter's task.* synthesis.
* Returns true when the notification was fully handled (must not reach
* parent-timeline mapping).
*/
const { handleRawNotification } = createCodexNotifications({
collabChildAgentsRef,
sessionRef,
emitEvent,
options,
collabChildLiveTurnsRef,
suppressMemoryConsolidationNotification,
collabReceiverTurnsRef,
approvalCorrelationsRef,
});
const currentSessionProviderThreadId = Effect.map(Ref.get(sessionRef), currentProviderThreadId);
yield* client.handleServerNotification("thread/started", (payload) =>
currentSessionProviderThreadId.pipe(
Effect.flatMap((providerThreadId) => {
if (providerThreadId && payload.thread.id !== providerThreadId) {
return Effect.void;
}
return updateSession(sessionRef, {
resumeCursor: { threadId: payload.thread.id },
});
}),
),
);
yield* client.handleServerNotification("turn/started", (payload) =>
currentSessionProviderThreadId.pipe(
Effect.flatMap((providerThreadId) => {
if (providerThreadId && payload.threadId !== providerThreadId) {
return Effect.void;
}
return updateSession(sessionRef, {
status: "running",
activeTurnId: TurnId.make(payload.turn.id),
});
}),
),
);
yield* client.handleServerNotification("turn/completed", (payload) =>
currentSessionProviderThreadId.pipe(
Effect.flatMap((providerThreadId) => {
if (providerThreadId && payload.threadId !== providerThreadId) {
return Effect.void;
}
const lastError =
payload.turn.status === "failed" && "error" in payload.turn && payload.turn.error
? payload.turn.error.message
: undefined;
return updateSession(sessionRef, {
status: payload.turn.status === "failed" ? "error" : "ready",
activeTurnId: undefined,
...(lastError ? { lastError } : {}),
});
}),
),
);
yield* client.handleServerNotification("error", (payload) =>
currentSessionProviderThreadId.pipe(
Effect.flatMap((providerThreadId) => {
const payloadThreadId = payload.threadId;
if (providerThreadId && payloadThreadId && payloadThreadId !== providerThreadId) {
return Effect.void;
}
const errorMessage = payload.error.message;
const willRetry = payload.willRetry;
return updateSession(sessionRef, {
status: willRetry ? "running" : "error",
...(errorMessage ? { lastError: errorMessage } : {}),
});
}),
),
);
const { registerHandlers, respondToRequest, respondToUserInput } = createCodexServerRequests({
client,
options,
sessionRef,
pendingApprovalsRef,
approvalCorrelationsRef,
pendingUserInputsRef,
randomUUIDv4,
emitEvent,
});
yield* registerHandlers;
const registerServerNotification = <M extends CodexRpc.ServerNotificationMethod>(method: M) =>
client.handleServerNotification(method, (params) =>
Queue.offer(serverNotifications, codexServerNotification(method, params)).pipe(
Effect.asVoid,
),
);
yield* Effect.forEach(
Object.values(CodexRpc.SERVER_NOTIFICATION_METHODS),
registerServerNotification,
{ concurrency: 1, discard: true },
);
yield* Stream.fromQueue(serverNotifications).pipe(
Stream.runForEach(handleRawNotification),
Effect.forkIn(runtimeScope),
);
const stderrRemainderRef = yield* Ref.make("");
yield* child.stderr.pipe(
Stream.decodeText(),
Stream.runForEach((chunk) =>
Ref.modify(stderrRemainderRef, (current) => {
const combined = current + chunk;
const lines = combined.split("\n");
const remainder = lines.pop() ?? "";
return [lines.map((line) => line.replace(/\r$/, "")), remainder] as const;
}).pipe(
Effect.flatMap((lines) =>
Effect.forEach(
lines,
(line) => {
const classified = classifyCodexStderrLine(line);
if (!classified) {
return Effect.void;
}
return emitEvent({
kind: "notification",
threadId: options.threadId,
method: "process/stderr",
message: classified.message,
});
},
{ discard: true },
),
),
),
),
Effect.forkIn(runtimeScope),
);
yield* child.exitCode.pipe(
Effect.flatMap((exitCode) =>
Ref.get(closedRef).pipe(
Effect.flatMap((closed) => {
if (closed) {
return Effect.void;
}
const nextStatus = exitCode === 0 ? "closed" : "error";
return updateSession(sessionRef, {
status: nextStatus,
activeTurnId: undefined,
}).pipe(
Effect.andThen(
emitSessionEvent(
"session/exited",
exitCode === 0
? "Codex App Server exited."
: `Codex App Server exited with code ${exitCode}.`,
),
),
);
}),
),
),
Effect.forkIn(runtimeScope),
);
const start = Effect.fn("CodexSessionRuntime.start")(function* () {
yield* emitSessionEvent("session/connecting", "Starting Codex App Server session.");
yield* client.request("initialize", buildCodexInitializeParams());
yield* client.notify("initialized", undefined);
const requestedModel = normalizeCodexModelSlug(options.model);
const opened = yield* openCodexThread({
client,
threadId: options.threadId,
runtimeMode: options.runtimeMode,
cwd: options.cwd,
requestedModel,
serviceTier: options.serviceTier,
resumeThreadId: readResumeCursorThreadId(options.resumeCursor),
});
const providerThreadId = opened.thread.id;
const session = {
...(yield* Ref.get(sessionRef)),
status: "ready",
cwd: opened.cwd,
model: opened.model,
resumeCursor: { threadId: providerThreadId },
updatedAt: yield* nowIso,
} satisfies ProviderSession;
yield* Ref.set(sessionRef, session);
yield* emitSessionEvent("session/ready", "Codex App Server session ready.");
return session;
});
const readProviderThreadId = Effect.gen(function* () {
const providerThreadId = currentProviderThreadId(yield* Ref.get(sessionRef));
if (!providerThreadId) {
return yield* new CodexSessionRuntimeThreadIdMissingError({
threadId: options.threadId,
});
}
return providerThreadId;
});
const close = Effect.gen(function* () {
const alreadyClosed = yield* Ref.getAndSet(closedRef, true);
if (alreadyClosed) {
return;
}
yield* settlePendingApprovals("cancel");
yield* settlePendingUserInputs({});
yield* updateSession(sessionRef, {
status: "closed",
activeTurnId: undefined,
});
yield* emitSessionEvent("session/closed", "Session stopped").pipe(
Effect.catch((cause) =>
Effect.logError("Failed to emit Codex session closed event.", { cause }),
),
);
yield* Scope.close(runtimeScope, Exit.void);
yield* Queue.shutdown(serverNotifications);
yield* Queue.shutdown(events);
});
return {
start,
getSession: Ref.get(sessionRef),
sendTurn: (input) =>
Effect.gen(function* () {
const providerThreadId = yield* readProviderThreadId;
if (hasConfiguredMcpServer(options.appServerArgs)) {
yield* client.request("config/mcpServer/reload", undefined).pipe(
Effect.catch((cause) =>
Effect.logWarning("Failed to refresh Codex MCP tool catalog before turn.", {
cause,
}),
),
);
}
const normalizedModel = normalizeCodexModelSlug(
input.model ?? (yield* Ref.get(sessionRef)).model,
);
const params = yield* buildTurnStartParams({
threadId: providerThreadId,
runtimeMode: options.runtimeMode,
...(input.input ? { prompt: input.input } : {}),
...(input.attachments ? { attachments: input.attachments } : {}),
...(normalizedModel ? { model: normalizedModel } : {}),
...(input.serviceTier ? { serviceTier: input.serviceTier } : {}),
...(input.effort ? { effort: input.effort } : {}),
...(input.interactionMode ? { interactionMode: input.interactionMode } : {}),
// Derived from the session's own MCP configuration rather than the
// setting, so the prompt describes the tools this turn actually
// has even if the setting changed after the session started.
browserToolsAvailable: hasConfiguredMcpServer(options.appServerArgs),
});
const rawResponse = yield* client.raw.request("turn/start", params);
const response = yield* decodeV2TurnStartResponse(rawResponse).pipe(
Effect.mapError((error) =>
CodexErrors.CodexAppServerProtocolParseError.fromSchemaError(
"decode-response-payload",
error,
{ method: "turn/start" },
),
),
);
const turnId = TurnId.make(response.turn.id);
yield* updateSession(sessionRef, (session) => ({
status: "running",
// Codex accepts follow-ups while the current turn is still
// running. The response contains the queued turn id, but
// turn/interrupt only accepts the id that is active now.
activeTurnId: session.activeTurnId ?? turnId,
...(normalizedModel ? { model: normalizedModel } : {}),
}));
const resumedProviderThreadId = currentProviderThreadId(yield* Ref.get(sessionRef));
return {
threadId: options.threadId,
turnId,
...(resumedProviderThreadId
? { resumeCursor: { threadId: resumedProviderThreadId } }
: {}),
} satisfies ProviderTurnStartResult;
}),
interruptTurn: (turnId) =>
Effect.gen(function* () {
const providerThreadId = yield* readProviderThreadId;
const session = yield* Ref.get(sessionRef);
// Stop-everything: children are full threads with their own turns;
// interrupting only the parent leaves the fleet running. Interrupt
// each live child turn first, best-effort per child, BOUNDED: the
// transport awaits an unbounded Deferred per request, so a wedged
// child would otherwise block the parent interrupt forever —
// exactly during the runaway fleet where Stop matters most
// (review finding). Per-child and overall deadlines guarantee the
// parent interrupt below always runs.
const liveChildTurns = yield* Ref.get(collabChildLiveTurnsRef);
yield* Effect.forEach(
Array.from(liveChildTurns.entries()),
([childThreadId, childTurnId]) =>
client
.request("turn/interrupt", {
threadId: childThreadId,
turnId: childTurnId,
})
.pipe(Effect.timeoutOption("3 seconds"), Effect.ignore),
{ concurrency: 8, discard: true },
).pipe(Effect.timeoutOption("10 seconds"), Effect.ignore);
const effectiveTurnId = turnId ?? session.activeTurnId;
if (!effectiveTurnId) {
return;
}
yield* client.request("turn/interrupt", {
threadId: providerThreadId,
turnId: effectiveTurnId,
});
}),
readThread: Effect.gen(function* () {
const providerThreadId = yield* readProviderThreadId;
const response = yield* client.request("thread/read", {
threadId: providerThreadId,
includeTurns: true,
});
return parseThreadSnapshot(response);
}),
rollbackThread: (numTurns) =>
Effect.gen(function* () {
const providerThreadId = yield* readProviderThreadId;
const response = yield* client.request("thread/rollback", {
threadId: providerThreadId,
numTurns,
});
yield* updateSession(sessionRef, {
status: "ready",
activeTurnId: undefined,
});
return parseThreadSnapshot(response);
}),
uploadFeedback: (reason) =>
Effect.gen(function* () {
const providerThreadId = yield* readProviderThreadId;
return yield* client.request("feedback/upload", {
classification: "bug",
includeLogs: true,
...(reason ? { reason } : {}),
threadId: providerThreadId,
});
}),
respondToRequest,
respondToUserInput,
events: Stream.fromQueue(events),
close,
} satisfies CodexSessionRuntimeShape;
});
export {
hasConfiguredMcpServer,
CodexResumeCursorSchema,
type CodexTurnStartParamsWithCollaborationMode,
type CodexResumeCursor,
buildTurnStartParams,
} from "./codex/CodexRuntimeRequests.ts";
export {
type CodexSessionRuntimeOptions,
type CodexSessionRuntimeSendTurnInput,
type CodexThreadTurnSnapshot,
type CodexThreadSnapshot,
type CodexSessionRuntimeShape,
} from "./codex/CodexRuntimeState.ts";
export {
type CodexSessionRuntimeError,
CodexSessionRuntimePendingApprovalNotFoundError,
CodexSessionRuntimePendingUserInputNotFoundError,
CodexSessionRuntimeInvalidUserInputAnswersError,
CodexSessionRuntimeThreadIdMissingError,
} from "./codex/CodexRuntimeErrors.ts";
export { describeMcpElicitation, toMcpElicitationResponse } from "./codex/CodexMcpElicitation.ts";
export { isRecoverableThreadResumeError, openCodexThread } from "./codex/CodexRuntimeOpening.ts";
export {
memoryConsolidationNotificationFilter,
type CodexChildNotificationRoute,
routeCodexChildNotification,
} from "./codex/CodexRuntimeNotifications.ts";