1import type { V2TurnStartParams__AdditionalContextEntry } from "effect-codex-app-server/schema";
2import { buildRuntimeInstructions } from "@t3tools/provider-core/server/runtimeInstructions";
3
4import {
5 T3_CODE_BROWSER_TOOL_INSTRUCTIONS,
6 T3_CODE_DEVICE_TOOL_INSTRUCTIONS,
7 T3_CODE_ORCHESTRATION_SECTIONS,
8} from "@t3tools/provider-core/server/orchestrationInstructions";
9
10/** Codex silently truncates additionalContext values over 1,000 tokens, counted as UTF-8 bytes / 4. */
11export const CODEX_ADDITIONAL_CONTEXT_VALUE_MAX_BYTES = 4_000;
12
13export interface T3CodeToolAvailability {
14 readonly browser: boolean;
15 readonly device: boolean;
16}
17
18const normalizeAvailability = (
19 availability: boolean | T3CodeToolAvailability,
20): T3CodeToolAvailability =>
21 typeof availability === "boolean" ? { browser: availability, device: false } : availability;
22
23/** Instructions for unavailable tools would steer the model away from its remaining automation. */
24const toolInstructions = (availability: boolean | T3CodeToolAvailability): string => {
25 const tools = normalizeAvailability(availability);
26 return [
27 tools.browser ? T3_CODE_BROWSER_TOOL_INSTRUCTIONS : "",
28 tools.device ? T3_CODE_DEVICE_TOOL_INSTRUCTIONS : "",
29 ]
30 .filter(Boolean)
31 .join("\n\n");
32};
33
34export interface CodexRuntimeInfo {
35 readonly model: string;
36 readonly modelName?: string | undefined;
37 readonly reasoningEffort?: string | undefined;
38}
39
40/** Keep this outside collaboration mode; model-catalog mode text overrides client developer_instructions. */
41export function buildCodexAdditionalContext(
42 runtime: CodexRuntimeInfo,
43 toolsAvailable: boolean | T3CodeToolAvailability = true,
44): Record<string, V2TurnStartParams__AdditionalContextEntry> {
45 const tools = toolInstructions(toolsAvailable);
46 // Split values to fit per-entry caps; number keys because Codex emits them in key order.
47 return {
48 ...Object.fromEntries(
49 T3_CODE_ORCHESTRATION_SECTIONS.map((section, index) => [
50 `t3_code_orchestration_${String(index + 1).padStart(2, "0")}`,
51 { kind: "application" as const, value: section },
52 ]),
53 ),
54 t3_code_runtime: {
55 kind: "application",
56 value: buildRuntimeInstructions({ harness: "Codex", ...runtime }),
57 },
58 ...(tools ? { t3_code_tools: { kind: "application", value: tools } } : {}),
59 };
60}