@niwa-labs/harness-codex 0.0.0-stage → 0.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/index.ts ADDED
@@ -0,0 +1,128 @@
1
+ /**
2
+ * The Codex harness kind.
3
+ *
4
+ * It serves the reading side and the control side. The reading side reads the rollouts Codex
5
+ * writes; the control side drives Codex over `codex app-server`. It has no insert side.
6
+ */
7
+
8
+ import { homedir } from "node:os";
9
+ import { join } from "node:path";
10
+
11
+ import { NO_INSERT, NoOptions, UNSUPPORTED, VERIFIED, defineHarnessKind, kindOptions } from "@niwa-labs/harness";
12
+ import type { HarnessBinding, InstanceOptions, KindCapabilities, SideCapabilities } from "@niwa-labs/harness";
13
+
14
+ import { CODEX_LAUNCH, codexControl } from "./control.ts";
15
+ import type { CodexControlOptions } from "./control.ts";
16
+ import { CodexReading } from "./reading.ts";
17
+
18
+ export { CodexReading } from "./reading.ts";
19
+ export type { CodexReadingOptions } from "./reading.ts";
20
+ export { CODEX_LAUNCH, codexControl } from "./control.ts";
21
+ export type { CodexControlOptions, CodexSessionControl } from "./control.ts";
22
+
23
+ /**
24
+ * The sides a Codex instance has by default.
25
+ *
26
+ * The reading side lists and reads the rollouts Codex writes; it does not follow a session while
27
+ * it grows. The control side starts, resumes, sends, interrupts and asks; Codex answers a
28
+ * question with a value that passed the schema, by itself.
29
+ */
30
+ export const codexSides: SideCapabilities = {
31
+ reading: { list: true, read: true, watch: false },
32
+ control: {
33
+ start: true,
34
+ resume: true,
35
+ send: true,
36
+ interrupt: true,
37
+ ask: true,
38
+ structuredOutput: true,
39
+ launch: CODEX_LAUNCH,
40
+ tools: { niwaOnly: false, allow: false },
41
+ },
42
+ };
43
+
44
+ /** What the kind declares it can serve, proved against a live Codex. */
45
+ export const CODEX_CAPABILITIES: KindCapabilities = {
46
+ reading: { list: VERIFIED, read: VERIFIED, watch: UNSUPPORTED },
47
+ control: {
48
+ start: VERIFIED,
49
+ resume: VERIFIED,
50
+ send: VERIFIED,
51
+ interrupt: VERIFIED,
52
+ ask: VERIFIED,
53
+ structuredOutput: VERIFIED,
54
+ launch: { model: VERIFIED, effort: CODEX_LAUNCH.effort, modes: CODEX_LAUNCH.modes },
55
+ tools: { niwaOnly: UNSUPPORTED, allow: UNSUPPORTED },
56
+ },
57
+ insert: NO_INSERT,
58
+ };
59
+
60
+ /** The block a Codex session takes at its start: `codex`, with no option of its own yet. */
61
+ export const CODEX_OPTIONS = kindOptions("codex", NoOptions);
62
+
63
+ /**
64
+ * How a Codex installation is found: the program that runs it, and the directory it keeps its
65
+ * rollouts in.
66
+ */
67
+ const CODEX_DETECTION = {
68
+ binary: "codex",
69
+ home: "~/.codex",
70
+ } as const;
71
+
72
+ /** What an installation of Codex is given: its id, home and model, and how its control side is set up. */
73
+ export interface CodexInstanceOptions extends InstanceOptions {
74
+ /** Where the rollouts are, when not in `<home>/sessions`. */
75
+ readonly sessionsDir?: string;
76
+ /**
77
+ * How the control side is set up: the effort, the working mode its sessions run in and the binary
78
+ * it drives. Its own defaults are used when it is absent.
79
+ */
80
+ readonly control?: Omit<CodexControlOptions, "harness" | "home" | "model">;
81
+ }
82
+
83
+ /** What the caller names of one installation: every part has a default. */
84
+ export type CodexOptions = Partial<CodexInstanceOptions>;
85
+
86
+ function defaultHome(): string {
87
+ const named = process.env["CODEX_HOME"];
88
+ return named !== undefined && named !== "" ? named : join(homedir(), ".codex");
89
+ }
90
+
91
+ /**
92
+ * The kind "codex". Each installation is bound to its own home (default `$CODEX_HOME`, else
93
+ * `~/.codex`: where Codex itself looks): its rollouts are read from there, and its processes are
94
+ * started with it, so the sessions they write are the ones the reading side lists.
95
+ */
96
+ export const codexKind = defineHarnessKind<CodexInstanceOptions>({
97
+ name: "codex",
98
+ capabilities: CODEX_CAPABILITIES,
99
+ implements: ["reading", "control"],
100
+ sides: codexSides,
101
+ detect: CODEX_DETECTION,
102
+ options: CODEX_OPTIONS,
103
+ home: defaultHome,
104
+ // Its program (a launcher that runs the app's own build), its home (sign-in, rollouts, history,
105
+ // configuration, caches) and the endpoints of its model and its sign-in. A session ran a turn in a
106
+ // box closed to reading with this profile alone.
107
+ profile: {
108
+ status: "verified",
109
+ of: ({ home, sessionsDir, control }) => ({ bin }) => ({
110
+ read: bin(control?.binary ?? "codex"),
111
+ write: [home, ...(sessionsDir === undefined ? [] : [sessionsDir])],
112
+ net: ["api.openai.com", "chatgpt.com"],
113
+ }),
114
+ },
115
+ bind: ({ id, home, model, sessionsDir, control }) => ({
116
+ reading: new CodexReading({ harness: id, home, ...(sessionsDir === undefined ? {} : { sessionsDir }) }),
117
+ control: codexControl({ ...(control ?? {}), ...(model === undefined ? {} : { model }), harness: id, home }),
118
+ }),
119
+ });
120
+
121
+ /** One installation of Codex: `codex` at its default home unless the options say otherwise. */
122
+ export function codex(options: CodexOptions = {}): HarnessBinding {
123
+ return codexKind.bind({ ...options, id: options.id ?? "codex" });
124
+ }
125
+
126
+ export { codexSkills } from "./skills.ts";
127
+ export { nativeIdOfFileName } from "./paths.ts";
128
+ export { FIXTURE_HARNESS as CODEX_HARNESS, writeCodexFixtures } from "./fixtures.ts";
package/src/paths.ts ADDED
@@ -0,0 +1,42 @@
1
+ /**
2
+ * Where a Codex installation keeps its sessions, and how a rollout file is named.
3
+ *
4
+ * The native layout is `~/.codex/sessions/YYYY/MM/DD/rollout-YYYY-MM-DDTHH-MM-SS-<uuid>.jsonl`.
5
+ * Codex compresses cold rollouts itself into the same file with a `.zst` suffix: the same JSONL,
6
+ * in a zstd container (`codex-rs/rollout/src/compression.rs`).
7
+ *
8
+ * The id of the session is the uuid in the file name. Codex writes it into the first
9
+ * `session_meta` as well, and the two agree; the file name is used because it is there even when
10
+ * the session metadata is missing or unreadable.
11
+ */
12
+
13
+ /** The name of a rollout file: `rollout-<...>-<uuid>.jsonl`. */
14
+ const ROLLOUT_NAME = /^rollout-.+-([0-9a-fA-F-]{36})\.jsonl$/;
15
+
16
+ /**
17
+ * The suffix of the compressed copy of a rollout.
18
+ *
19
+ * It is `.zst`, not `.jsonl.zst`: the compressed file is the rollout with `.zst` added, so the
20
+ * name of the rollout is the name without it.
21
+ */
22
+ export const ZSTD_SUFFIX = ".zst";
23
+
24
+ /** The id in the name of a rollout file, or `null` when the name is not a rollout's. */
25
+ export function nativeIdOfFileName(name: string): string | null {
26
+ const base = name.endsWith(ZSTD_SUFFIX) ? name.slice(0, -ZSTD_SUFFIX.length) : name;
27
+ return ROLLOUT_NAME.exec(base)?.[1] ?? null;
28
+ }
29
+
30
+ /** Whether a file name is the compressed copy of a rollout. */
31
+ export function isCompressedName(name: string): boolean {
32
+ return name.endsWith(ZSTD_SUFFIX);
33
+ }
34
+
35
+ /**
36
+ * The base of a rollout path: the compressed copy is the same rollout, so the suffix is removed.
37
+ *
38
+ * It is what tells the two copies of one session apart from two sessions.
39
+ */
40
+ export function baseOfArtifact(path: string): string {
41
+ return path.endsWith(ZSTD_SUFFIX) ? path.slice(0, path.length - ZSTD_SUFFIX.length) : path;
42
+ }