@litfamily/litcodex 1.0.10 → 1.0.12
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/README-Ko-KR.md +17 -17
- package/README.md +19 -18
- package/dist/cli.js +11 -4
- package/dist/install/auto-handoff-doctor.d.ts +4 -0
- package/dist/install/auto-handoff-doctor.js +115 -0
- package/dist/install/doctor-render.js +2 -0
- package/dist/install/doctor.js +26 -1
- package/dist/install/types.d.ts +10 -0
- package/marketplace/plugins/litcodex/.codex-plugin/plugin.json +1 -1
- package/marketplace/plugins/litcodex/components/auto-update/package.json +1 -1
- package/marketplace/plugins/litcodex/components/comment-checker/package.json +1 -1
- package/marketplace/plugins/litcodex/components/git-bash/package.json +1 -1
- package/marketplace/plugins/litcodex/components/lit-loop/dist/auto-handoff-settings.d.ts +80 -0
- package/marketplace/plugins/litcodex/components/lit-loop/dist/auto-handoff-settings.js +368 -0
- package/marketplace/plugins/litcodex/components/lit-loop/dist/auto-handoff.d.ts +64 -0
- package/marketplace/plugins/litcodex/components/lit-loop/dist/auto-handoff.js +311 -0
- package/marketplace/plugins/litcodex/components/lit-loop/dist/cli.js +5 -1
- package/marketplace/plugins/litcodex/components/lit-loop/dist/hook-cli.d.ts +11 -2
- package/marketplace/plugins/litcodex/components/lit-loop/dist/hook-cli.js +113 -6
- package/marketplace/plugins/litcodex/components/lit-loop/package.json +1 -1
- package/marketplace/plugins/litcodex/components/lsp/package.json +1 -1
- package/marketplace/plugins/litcodex/components/rules/package.json +1 -1
- package/marketplace/plugins/litcodex/components/start-work-continuation/package.json +1 -1
- package/marketplace/plugins/litcodex/components/telemetry/package.json +1 -1
- package/marketplace/plugins/litcodex/components/wikify-knowledge/package.json +1 -1
- package/marketplace/plugins/litcodex/hooks/hooks.json +20 -0
- package/node_modules/@litcodex/lit-loop/README.md +10 -0
- package/node_modules/@litcodex/lit-loop/dist/auto-handoff-settings.d.ts +80 -0
- package/node_modules/@litcodex/lit-loop/dist/auto-handoff-settings.js +368 -0
- package/node_modules/@litcodex/lit-loop/dist/auto-handoff.d.ts +64 -0
- package/node_modules/@litcodex/lit-loop/dist/auto-handoff.js +311 -0
- package/node_modules/@litcodex/lit-loop/dist/cli.js +5 -1
- package/node_modules/@litcodex/lit-loop/dist/hook-cli.d.ts +11 -2
- package/node_modules/@litcodex/lit-loop/dist/hook-cli.js +113 -6
- package/node_modules/@litcodex/lit-loop/package.json +1 -1
- package/package.json +2 -2
- package/readme-assets/badge-version.svg +1 -1
- package/readme-assets/ab-simple/assets/s11-baseline-desktop.webp +0 -0
- package/readme-assets/ab-simple/assets/s11-baseline-phone.webp +0 -0
- package/readme-assets/ab-simple/assets/s11-lit-desktop.webp +0 -0
- package/readme-assets/ab-simple/assets/s11-lit-phone.webp +0 -0
- package/readme-assets/ab-simple/assets/s3-baseline-desktop.webp +0 -0
- package/readme-assets/ab-simple/assets/s3-baseline-phone.webp +0 -0
- package/readme-assets/ab-simple/assets/s3-lit-desktop.webp +0 -0
- package/readme-assets/ab-simple/assets/s3-lit-phone.webp +0 -0
- package/readme-assets/ab-simple/assets/s4-baseline-desktop.webp +0 -0
- package/readme-assets/ab-simple/assets/s4-baseline-phone.webp +0 -0
- package/readme-assets/ab-simple/assets/s4-lit-desktop.webp +0 -0
- package/readme-assets/ab-simple/assets/s4-lit-phone.webp +0 -0
- package/readme-assets/ab-simple/assets/s5-baseline-slides.webp +0 -0
- package/readme-assets/ab-simple/assets/s5-lit-slides.webp +0 -0
- package/readme-assets/ab-simple/assets/s7-lit-diagram.webp +0 -0
- package/readme-assets/ab-simple/assets/s8-baseline-slides.webp +0 -0
- package/readme-assets/ab-simple/assets/s8-lit-slides.webp +0 -0
- package/readme-assets/ab-simple/assets/s9-lit-pages.webp +0 -0
|
@@ -0,0 +1,368 @@
|
|
|
1
|
+
// src/auto-handoff-settings.ts — the user-controlled switch for automatic handoff.
|
|
2
|
+
//
|
|
3
|
+
// Off by default. The user turns it on with the exact prompt `lit-handoff auto on <percent>` (or sets
|
|
4
|
+
// `LITCODEX_AUTO_HANDOFF=1` plus `LITCODEX_AUTO_HANDOFF_PERCENT`), turns it off with
|
|
5
|
+
// `lit-handoff auto off`, and reads the state with `lit-handoff auto status`. The percent is never
|
|
6
|
+
// hard-coded: `on` without a number reuses the last value the user stored and asks for one when there
|
|
7
|
+
// is none. A percent that is not a whole number from 1 to 99 keeps the feature off and is reported.
|
|
8
|
+
//
|
|
9
|
+
// Command-set values live in `.litcodex/auto-handoff/settings.json` under the project folder. When the
|
|
10
|
+
// feature is turned on by command, the same percent is written to the PROJECT `.codex/config.toml` as
|
|
11
|
+
// `model_post_turn_compact_threshold_percent`, so Codex itself compacts once the turn that saved the
|
|
12
|
+
// handoff is over. The key is written inside a marked block and removed again by `off`; a key the user
|
|
13
|
+
// wrote by hand is never touched. Codex reads a project's `.codex/config.toml` only when the project is
|
|
14
|
+
// trusted in `$CODEX_HOME/config.toml`, so every claim that Codex compacts also checks that trust.
|
|
15
|
+
import { randomBytes } from "node:crypto";
|
|
16
|
+
import { closeSync, constants, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, rmdirSync, unlinkSync, writeSync, } from "node:fs";
|
|
17
|
+
import { homedir } from "node:os";
|
|
18
|
+
import { dirname, isAbsolute, join } from "node:path";
|
|
19
|
+
export const AUTO_HANDOFF_FLAG_ENV = "LITCODEX_AUTO_HANDOFF";
|
|
20
|
+
export const AUTO_HANDOFF_PERCENT_ENV = "LITCODEX_AUTO_HANDOFF_PERCENT";
|
|
21
|
+
export const AUTO_HANDOFF_DIR = ".litcodex/auto-handoff";
|
|
22
|
+
export const AUTO_HANDOFF_SETTINGS_FILE = "settings.json";
|
|
23
|
+
export const HOST_COMPACT_KEY = "model_post_turn_compact_threshold_percent";
|
|
24
|
+
export const HOST_COMPACT_BEGIN = "# litcodex automatic handoff (managed by `lit-handoff auto`; `lit-handoff auto off` removes it)";
|
|
25
|
+
const NO_FOLLOW = constants.O_NOFOLLOW ?? 0;
|
|
26
|
+
const MAX_FILE_BYTES = 256 * 1024;
|
|
27
|
+
const DEFAULT_STORED = Object.freeze({ enabled: false, percent: null });
|
|
28
|
+
/** A whole number from 1 to 99 written as plain digits, else null. */
|
|
29
|
+
export function parsePercent(raw) {
|
|
30
|
+
const text = raw?.trim() ?? "";
|
|
31
|
+
if (!/^\d{1,2}$/u.test(text))
|
|
32
|
+
return null;
|
|
33
|
+
const value = Number(text);
|
|
34
|
+
return value >= 1 && value <= 99 ? value : null;
|
|
35
|
+
}
|
|
36
|
+
export function settingsPath(repoRoot) {
|
|
37
|
+
return join(repoRoot, AUTO_HANDOFF_DIR, AUTO_HANDOFF_SETTINGS_FILE);
|
|
38
|
+
}
|
|
39
|
+
function isRecord(value) {
|
|
40
|
+
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
41
|
+
}
|
|
42
|
+
/** Read a small regular file; null when missing, a symlink, too large, or unreadable. */
|
|
43
|
+
export function readSmallFile(path) {
|
|
44
|
+
let fd;
|
|
45
|
+
try {
|
|
46
|
+
const stat = lstatSync(path, { throwIfNoEntry: false });
|
|
47
|
+
if (stat === undefined || !stat.isFile() || stat.size > MAX_FILE_BYTES)
|
|
48
|
+
return null;
|
|
49
|
+
fd = openSync(path, constants.O_RDONLY | NO_FOLLOW);
|
|
50
|
+
}
|
|
51
|
+
catch {
|
|
52
|
+
return null;
|
|
53
|
+
}
|
|
54
|
+
try {
|
|
55
|
+
return readFileSync(fd, "utf8");
|
|
56
|
+
}
|
|
57
|
+
catch {
|
|
58
|
+
return null;
|
|
59
|
+
}
|
|
60
|
+
finally {
|
|
61
|
+
closeSync(fd);
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
/** The stored choice; a missing, malformed or hand-edited file reads as "off, no percent". */
|
|
65
|
+
export function readStoredAutoHandoff(repoRoot) {
|
|
66
|
+
if (!isAbsolute(repoRoot))
|
|
67
|
+
return { stored: DEFAULT_STORED, warning: null };
|
|
68
|
+
const raw = readSmallFile(settingsPath(repoRoot));
|
|
69
|
+
if (raw === null)
|
|
70
|
+
return { stored: DEFAULT_STORED, warning: null };
|
|
71
|
+
try {
|
|
72
|
+
const parsed = JSON.parse(raw);
|
|
73
|
+
if (!isRecord(parsed))
|
|
74
|
+
throw new Error("not an object");
|
|
75
|
+
const percent = parsed["percent"] === null ? null : parsePercent(String(parsed["percent"]));
|
|
76
|
+
const warning = parsed["percent"] !== null && percent === null
|
|
77
|
+
? "The stored percent is not a whole number from 1 to 99 and was ignored."
|
|
78
|
+
: null;
|
|
79
|
+
return { stored: { enabled: parsed["enabled"] === true, percent }, warning };
|
|
80
|
+
}
|
|
81
|
+
catch {
|
|
82
|
+
return {
|
|
83
|
+
stored: DEFAULT_STORED,
|
|
84
|
+
warning: `${AUTO_HANDOFF_DIR}/${AUTO_HANDOFF_SETTINGS_FILE} could not be read, so automatic handoff stays off.`,
|
|
85
|
+
};
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
function shown(raw) {
|
|
89
|
+
const clean = raw.replace(/[^\x20-\x7e]/gu, "?");
|
|
90
|
+
return clean.length > 24 ? `${clean.slice(0, 24)}...` : clean;
|
|
91
|
+
}
|
|
92
|
+
/**
|
|
93
|
+
* Combine the environment with the stored choice. The environment wins when it is set: `=1` turns the
|
|
94
|
+
* feature on and `=0` turns it off. The percent comes from its variable first, then from the stored
|
|
95
|
+
* value. Nothing is active without a valid percent.
|
|
96
|
+
*/
|
|
97
|
+
export function resolveAutoHandoff(env, stored, storedWarning = null) {
|
|
98
|
+
const warnings = [];
|
|
99
|
+
if (storedWarning !== null)
|
|
100
|
+
warnings.push(storedWarning);
|
|
101
|
+
const flag = env[AUTO_HANDOFF_FLAG_ENV]?.trim() ?? "";
|
|
102
|
+
if (flag !== "" && flag !== "1" && flag !== "0") {
|
|
103
|
+
warnings.push(`${AUTO_HANDOFF_FLAG_ENV}=${shown(flag)} is not 1 or 0 and was ignored.`);
|
|
104
|
+
}
|
|
105
|
+
const envDecision = flag === "1" ? true : flag === "0" ? false : null;
|
|
106
|
+
const enabled = envDecision ?? stored.enabled;
|
|
107
|
+
const rawPercent = env[AUTO_HANDOFF_PERCENT_ENV]?.trim() ?? "";
|
|
108
|
+
const envPercent = rawPercent === "" ? null : parsePercent(rawPercent);
|
|
109
|
+
const envPercentInvalid = rawPercent !== "" && envPercent === null;
|
|
110
|
+
if (envPercentInvalid) {
|
|
111
|
+
warnings.push(`${AUTO_HANDOFF_PERCENT_ENV}=${shown(rawPercent)} is not a whole number from 1 to 99, so automatic handoff stays off.`);
|
|
112
|
+
}
|
|
113
|
+
const percent = envPercentInvalid ? null : (envPercent ?? stored.percent);
|
|
114
|
+
const source = envDecision !== null || envPercent !== null ? "environment" : enabled ? "command" : "default";
|
|
115
|
+
if (enabled && !envPercentInvalid && percent === null) {
|
|
116
|
+
warnings.push(`Automatic handoff is on but has no percent. Run "lit-handoff auto on <percent>" or set ${AUTO_HANDOFF_PERCENT_ENV}.`);
|
|
117
|
+
}
|
|
118
|
+
return { active: enabled && percent !== null, percent, source, warnings };
|
|
119
|
+
}
|
|
120
|
+
export function loadAutoHandoffState(repoRoot, env) {
|
|
121
|
+
const { stored, warning } = readStoredAutoHandoff(repoRoot);
|
|
122
|
+
return resolveAutoHandoff(env, stored, warning);
|
|
123
|
+
}
|
|
124
|
+
// ── Safe small-file writes ───────────────────────────────────────────────────
|
|
125
|
+
function ensureDir(dir) {
|
|
126
|
+
try {
|
|
127
|
+
const stat = lstatSync(dir, { throwIfNoEntry: false });
|
|
128
|
+
if (stat === undefined) {
|
|
129
|
+
mkdirSync(dir, { recursive: true });
|
|
130
|
+
return true;
|
|
131
|
+
}
|
|
132
|
+
return stat.isDirectory();
|
|
133
|
+
}
|
|
134
|
+
catch {
|
|
135
|
+
return false;
|
|
136
|
+
}
|
|
137
|
+
}
|
|
138
|
+
/** Atomic write that refuses to go through a symlink or replace anything but a regular file. */
|
|
139
|
+
export function writeSmallFile(path, text) {
|
|
140
|
+
if (!ensureDir(dirname(path)))
|
|
141
|
+
return false;
|
|
142
|
+
const tmp = `${path}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
|
|
143
|
+
try {
|
|
144
|
+
const existing = lstatSync(path, { throwIfNoEntry: false });
|
|
145
|
+
if (existing !== undefined && !existing.isFile())
|
|
146
|
+
return false;
|
|
147
|
+
const fd = openSync(tmp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | NO_FOLLOW, 0o644);
|
|
148
|
+
try {
|
|
149
|
+
writeSync(fd, text);
|
|
150
|
+
}
|
|
151
|
+
finally {
|
|
152
|
+
closeSync(fd);
|
|
153
|
+
}
|
|
154
|
+
renameSync(tmp, path);
|
|
155
|
+
return true;
|
|
156
|
+
}
|
|
157
|
+
catch {
|
|
158
|
+
try {
|
|
159
|
+
unlinkSync(tmp);
|
|
160
|
+
}
|
|
161
|
+
catch {
|
|
162
|
+
// nothing was created
|
|
163
|
+
}
|
|
164
|
+
return false;
|
|
165
|
+
}
|
|
166
|
+
}
|
|
167
|
+
export function writeStoredAutoHandoff(repoRoot, stored) {
|
|
168
|
+
return writeSmallFile(settingsPath(repoRoot), `${JSON.stringify({ version: 1, ...stored })}\n`);
|
|
169
|
+
}
|
|
170
|
+
// ── Project config: Codex compacts after the handoff turn ────────────────────
|
|
171
|
+
const KEY_LINE = new RegExp(`^\\s*${HOST_COMPACT_KEY}\\s*=\\s*(\\d+)\\s*(?:#.*)?$`, "u");
|
|
172
|
+
export function projectConfigPath(repoRoot) {
|
|
173
|
+
return join(repoRoot, ".codex", "config.toml");
|
|
174
|
+
}
|
|
175
|
+
/** What the project's `.codex/config.toml` says about compacting after a turn. */
|
|
176
|
+
export function readProjectCompaction(repoRoot) {
|
|
177
|
+
const raw = readSmallFile(projectConfigPath(repoRoot));
|
|
178
|
+
if (raw === null)
|
|
179
|
+
return { kind: "absent" };
|
|
180
|
+
const lines = raw.split(/\r?\n/u);
|
|
181
|
+
for (let index = 0; index < lines.length; index += 1) {
|
|
182
|
+
const match = KEY_LINE.exec(lines[index] ?? "");
|
|
183
|
+
if (match?.[1] === undefined)
|
|
184
|
+
continue;
|
|
185
|
+
const percent = Number(match[1]);
|
|
186
|
+
return lines[index - 1] === HOST_COMPACT_BEGIN ? { kind: "managed", percent } : { kind: "user-set", percent };
|
|
187
|
+
}
|
|
188
|
+
return { kind: "absent" };
|
|
189
|
+
}
|
|
190
|
+
function codexHomeDir(env) {
|
|
191
|
+
const fromEnv = env["CODEX_HOME"]?.trim() ?? "";
|
|
192
|
+
return fromEnv === "" ? join(homedir(), ".codex") : fromEnv;
|
|
193
|
+
}
|
|
194
|
+
/** The project path a `[projects."<path>"]` table header names, else null. */
|
|
195
|
+
function projectOfHeader(header) {
|
|
196
|
+
const match = /^\s*projects\s*\.\s*(?:"((?:[^"\\]|\\.)*)"|'([^']*)')\s*$/u.exec(header);
|
|
197
|
+
if (match === null)
|
|
198
|
+
return null;
|
|
199
|
+
return match[1] !== undefined ? match[1].replace(/\\(["\\])/gu, "$1") : (match[2] ?? null);
|
|
200
|
+
}
|
|
201
|
+
/**
|
|
202
|
+
* True when `$CODEX_HOME/config.toml` marks this project trusted. Codex ignores a project's own
|
|
203
|
+
* `.codex/config.toml` until then, so an untrusted project never gets the compaction setting applied.
|
|
204
|
+
*/
|
|
205
|
+
export function projectTrusted(repoRoot, env) {
|
|
206
|
+
const raw = readSmallFile(join(codexHomeDir(env), "config.toml"));
|
|
207
|
+
if (raw === null)
|
|
208
|
+
return false;
|
|
209
|
+
const wanted = new Set([repoRoot]);
|
|
210
|
+
try {
|
|
211
|
+
wanted.add(realpathSync(repoRoot));
|
|
212
|
+
}
|
|
213
|
+
catch {
|
|
214
|
+
// the plain path is enough
|
|
215
|
+
}
|
|
216
|
+
let current = null;
|
|
217
|
+
for (const line of raw.split(/\r?\n/u)) {
|
|
218
|
+
const header = /^\s*\[(.*)\]\s*(?:#.*)?$/u.exec(line);
|
|
219
|
+
if (header?.[1] !== undefined) {
|
|
220
|
+
current = projectOfHeader(header[1]);
|
|
221
|
+
continue;
|
|
222
|
+
}
|
|
223
|
+
if (current !== null && wanted.has(current) && /^\s*trust_level\s*=\s*["']trusted["']\s*(?:#.*)?$/u.test(line)) {
|
|
224
|
+
return true;
|
|
225
|
+
}
|
|
226
|
+
}
|
|
227
|
+
return false;
|
|
228
|
+
}
|
|
229
|
+
/** True when Codex itself will compact once a turn ends with usage at or above `percent`. */
|
|
230
|
+
export function hostCompactsAt(repoRoot, percent, env) {
|
|
231
|
+
const current = readProjectCompaction(repoRoot);
|
|
232
|
+
return current.kind !== "absent" && current.percent <= percent && projectTrusted(repoRoot, env);
|
|
233
|
+
}
|
|
234
|
+
/** Write (or update) the marked block. A key the user wrote by hand stays as it is. */
|
|
235
|
+
export function writeProjectCompaction(repoRoot, percent) {
|
|
236
|
+
const path = projectConfigPath(repoRoot);
|
|
237
|
+
const stat = lstatSync(path, { throwIfNoEntry: false });
|
|
238
|
+
if (stat !== undefined && !stat.isFile())
|
|
239
|
+
return "failed";
|
|
240
|
+
const raw = stat === undefined ? "" : readSmallFile(path);
|
|
241
|
+
if (raw === null)
|
|
242
|
+
return "failed";
|
|
243
|
+
const current = readProjectCompaction(repoRoot);
|
|
244
|
+
if (current.kind === "user-set")
|
|
245
|
+
return "unchanged-user-key";
|
|
246
|
+
const block = `${HOST_COMPACT_BEGIN}\n${HOST_COMPACT_KEY} = ${percent}\n`;
|
|
247
|
+
if (current.kind === "managed") {
|
|
248
|
+
const lines = raw.split("\n");
|
|
249
|
+
const at = lines.findIndex((line) => KEY_LINE.test(line.replace(/\r$/u, "")));
|
|
250
|
+
lines[at] = `${HOST_COMPACT_KEY} = ${percent}`;
|
|
251
|
+
return writeSmallFile(path, lines.join("\n")) ? "written" : "failed";
|
|
252
|
+
}
|
|
253
|
+
return writeSmallFile(path, raw === "" ? block : `${block}\n${raw}`) ? "written" : "failed";
|
|
254
|
+
}
|
|
255
|
+
/** Remove only the marked block; delete the file (and an empty `.codex`) when nothing else is left. */
|
|
256
|
+
export function removeProjectCompaction(repoRoot) {
|
|
257
|
+
const path = projectConfigPath(repoRoot);
|
|
258
|
+
if (readProjectCompaction(repoRoot).kind !== "managed")
|
|
259
|
+
return "nothing-to-remove";
|
|
260
|
+
const raw = readSmallFile(path);
|
|
261
|
+
if (raw === null)
|
|
262
|
+
return "failed";
|
|
263
|
+
const lines = raw.split("\n");
|
|
264
|
+
const at = lines.findIndex((line) => line.replace(/\r$/u, "") === HOST_COMPACT_BEGIN);
|
|
265
|
+
if (at < 0)
|
|
266
|
+
return "nothing-to-remove";
|
|
267
|
+
lines.splice(at, 2);
|
|
268
|
+
if (lines[at] === "" && (at === 0 || lines[at - 1] === ""))
|
|
269
|
+
lines.splice(at, 1);
|
|
270
|
+
const rest = lines.join("\n");
|
|
271
|
+
if (rest.trim() === "") {
|
|
272
|
+
try {
|
|
273
|
+
unlinkSync(path);
|
|
274
|
+
try {
|
|
275
|
+
rmdirSync(dirname(path));
|
|
276
|
+
}
|
|
277
|
+
catch {
|
|
278
|
+
// other files live there
|
|
279
|
+
}
|
|
280
|
+
return "removed";
|
|
281
|
+
}
|
|
282
|
+
catch {
|
|
283
|
+
return "failed";
|
|
284
|
+
}
|
|
285
|
+
}
|
|
286
|
+
return writeSmallFile(path, rest) ? "removed" : "failed";
|
|
287
|
+
}
|
|
288
|
+
/** Only the complete prompt `lit-handoff auto ...` (case-insensitive, edge whitespace allowed) is a route. */
|
|
289
|
+
export function parseAutoHandoffRoute(prompt) {
|
|
290
|
+
const match = /^\s*lit-handoff\s+auto(?:\s+(.*?))?\s*$/isu.exec(prompt);
|
|
291
|
+
if (match === null)
|
|
292
|
+
return null;
|
|
293
|
+
const words = (match[1] ?? "").split(/\s+/u).filter(Boolean);
|
|
294
|
+
const verb = words[0]?.toLowerCase();
|
|
295
|
+
if (verb === "on" && words.length <= 2)
|
|
296
|
+
return { action: "on", argument: words[1] ?? null };
|
|
297
|
+
if (verb === "off" && words.length === 1)
|
|
298
|
+
return { action: "off" };
|
|
299
|
+
if (verb === "status" && words.length === 1)
|
|
300
|
+
return { action: "status" };
|
|
301
|
+
return { action: "usage" };
|
|
302
|
+
}
|
|
303
|
+
const USAGE = "Usage: lit-handoff auto on <percent from 1 to 99> | lit-handoff auto off | lit-handoff auto status";
|
|
304
|
+
/** Sentence describing how the conversation gets compacted once the handoff is saved. */
|
|
305
|
+
function compactionSentence(repoRoot, percent, env) {
|
|
306
|
+
return hostCompactsAt(repoRoot, percent, env)
|
|
307
|
+
? "Codex compacts the conversation as soon as the turn that saved the handoff ends."
|
|
308
|
+
: "After the handoff is saved you will be asked to run /compact yourself.";
|
|
309
|
+
}
|
|
310
|
+
export function describeAutoHandoff(repoRoot, state, env) {
|
|
311
|
+
const lines = [];
|
|
312
|
+
if (state.active && state.percent !== null) {
|
|
313
|
+
const origin = state.source === "environment" ? "set by environment variables" : "set by command";
|
|
314
|
+
lines.push(`Automatic handoff is ON at ${state.percent}% (${origin}).`);
|
|
315
|
+
lines.push(compactionSentence(repoRoot, state.percent, env));
|
|
316
|
+
}
|
|
317
|
+
else {
|
|
318
|
+
lines.push("Automatic handoff is OFF.");
|
|
319
|
+
if (state.percent !== null)
|
|
320
|
+
lines.push(`Your last percent is ${state.percent}%; "lit-handoff auto on" turns it back on with that value.`);
|
|
321
|
+
}
|
|
322
|
+
for (const warning of state.warnings)
|
|
323
|
+
lines.push(`Warning: ${warning}`);
|
|
324
|
+
return lines.join(" ");
|
|
325
|
+
}
|
|
326
|
+
/** Apply a parsed route and return the one message the user sees. Never throws. */
|
|
327
|
+
export function applyAutoHandoffRoute(repoRoot, env, route) {
|
|
328
|
+
try {
|
|
329
|
+
if (route.action === "usage")
|
|
330
|
+
return USAGE;
|
|
331
|
+
const { stored } = readStoredAutoHandoff(repoRoot);
|
|
332
|
+
if (route.action === "status")
|
|
333
|
+
return describeAutoHandoff(repoRoot, loadAutoHandoffState(repoRoot, env), env);
|
|
334
|
+
const envNote = (env[AUTO_HANDOFF_FLAG_ENV]?.trim() ?? "") === ""
|
|
335
|
+
? ""
|
|
336
|
+
: ` ${AUTO_HANDOFF_FLAG_ENV} is set in the environment and takes priority over this command.`;
|
|
337
|
+
if (route.action === "off") {
|
|
338
|
+
if (!writeStoredAutoHandoff(repoRoot, { enabled: false, percent: stored.percent })) {
|
|
339
|
+
return "Automatic handoff could not save its setting (the project folder is not writable), so nothing changed.";
|
|
340
|
+
}
|
|
341
|
+
removeProjectCompaction(repoRoot);
|
|
342
|
+
const kept = stored.percent === null ? "" : ` Your last percent (${stored.percent}%) is kept for next time.`;
|
|
343
|
+
return `Automatic handoff is OFF.${kept}${envNote}`;
|
|
344
|
+
}
|
|
345
|
+
const percent = route.argument === null ? stored.percent : parsePercent(route.argument);
|
|
346
|
+
if (route.argument === null && percent === null) {
|
|
347
|
+
return "Which percent should trigger the handoff? Run: lit-handoff auto on <percent from 1 to 99> (for example 60).";
|
|
348
|
+
}
|
|
349
|
+
if (percent === null)
|
|
350
|
+
return `"${shown(route.argument ?? "")}" is not a whole number from 1 to 99. Nothing changed.`;
|
|
351
|
+
if (!writeStoredAutoHandoff(repoRoot, { enabled: true, percent })) {
|
|
352
|
+
return "Automatic handoff could not save its setting (the project folder is not writable), so nothing changed.";
|
|
353
|
+
}
|
|
354
|
+
const config = writeProjectCompaction(repoRoot, percent);
|
|
355
|
+
const untrusted = config === "written" && !projectTrusted(repoRoot, env)
|
|
356
|
+
? "Codex reads the project .codex/config.toml only after you trust this project, so until then you will be asked to run /compact yourself."
|
|
357
|
+
: "";
|
|
358
|
+
const asked = config === "unchanged-user-key"
|
|
359
|
+
? ` Your project .codex/config.toml already sets ${HOST_COMPACT_KEY}, so it was left as it is.`
|
|
360
|
+
: config === "failed"
|
|
361
|
+
? " The project .codex/config.toml could not be updated, so you will be asked to run /compact yourself."
|
|
362
|
+
: "";
|
|
363
|
+
return `Automatic handoff is ON at ${percent}%. When a conversation reaches ${percent}% of the context window, Codex is asked to save a handoff. ${untrusted === "" ? compactionSentence(repoRoot, percent, env) : untrusted}${asked}${envNote}`;
|
|
364
|
+
}
|
|
365
|
+
catch {
|
|
366
|
+
return "Automatic handoff hit an unexpected error and changed nothing.";
|
|
367
|
+
}
|
|
368
|
+
}
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
export declare const HANDOFF_MARKER_LABEL = "Auto-handoff session:";
|
|
2
|
+
export declare const SAVED_LINE_RUN_COMPACT = "Handoff saved. Run /compact now.";
|
|
3
|
+
export declare const SAVED_LINE_HOST_COMPACTS = "Handoff saved. Codex compacts the conversation next.";
|
|
4
|
+
export declare const RELOAD_EXCERPT_CHARS = 3000;
|
|
5
|
+
declare const STATE_VERSION = 1;
|
|
6
|
+
export type AutoHandoffPhase = "idle" | "fired" | "compacted" | "reloaded";
|
|
7
|
+
export interface AutoHandoffSession {
|
|
8
|
+
readonly version: typeof STATE_VERSION;
|
|
9
|
+
readonly sessionId: string;
|
|
10
|
+
readonly phase: AutoHandoffPhase;
|
|
11
|
+
readonly firedAt: number | null;
|
|
12
|
+
readonly firedPercent: number | null;
|
|
13
|
+
readonly lastPercent: number | null;
|
|
14
|
+
}
|
|
15
|
+
export interface ContextReading {
|
|
16
|
+
readonly percent: number;
|
|
17
|
+
readonly tokens: number;
|
|
18
|
+
readonly window: number;
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* Context used by the last model request, as a percent of the window Codex reports for the session.
|
|
22
|
+
* Codex's own post-turn compaction compares the same two numbers, so the hook and the host cross the
|
|
23
|
+
* threshold together. Null when the transcript has no usage yet.
|
|
24
|
+
*/
|
|
25
|
+
export declare function readContextPercent(transcriptPath: string | null | undefined): ContextReading | null;
|
|
26
|
+
export interface AutoHandoffStopInput {
|
|
27
|
+
readonly repoRoot: string;
|
|
28
|
+
readonly sessionId: string;
|
|
29
|
+
readonly transcriptPath: string | null | undefined;
|
|
30
|
+
readonly stopHookActive: boolean;
|
|
31
|
+
readonly env: NodeJS.ProcessEnv;
|
|
32
|
+
readonly now?: number;
|
|
33
|
+
}
|
|
34
|
+
export type AutoHandoffStopDecision = {
|
|
35
|
+
readonly decision: "pass";
|
|
36
|
+
} | {
|
|
37
|
+
readonly decision: "block";
|
|
38
|
+
readonly reason: string;
|
|
39
|
+
};
|
|
40
|
+
export declare function buildHandoffInstruction(sessionId: string, percent: number, threshold: number, hostCompacts: boolean): string;
|
|
41
|
+
/**
|
|
42
|
+
* Decide the Stop for one turn. Fires at most once per crossing: the record moves to "fired" before the
|
|
43
|
+
* instruction is returned, `stop_hook_active` never fires again, and the record is re-armed only after
|
|
44
|
+
* the context has been seen back under the percent.
|
|
45
|
+
*/
|
|
46
|
+
export declare function evaluateAutoHandoffStop(input: AutoHandoffStopInput): AutoHandoffStopDecision;
|
|
47
|
+
/** Mark a fired session as compacted. Sessions that never fired are left alone. */
|
|
48
|
+
export declare function recordCompaction(repoRoot: string, sessionId: string): void;
|
|
49
|
+
interface FreshHandoff {
|
|
50
|
+
readonly path: string;
|
|
51
|
+
readonly mtimeMs: number;
|
|
52
|
+
readonly text: string;
|
|
53
|
+
}
|
|
54
|
+
/** The newest HANDOFF file written after `since` that names `sessionId`; everything else is ignored. */
|
|
55
|
+
export declare function findFreshHandoff(repoRoot: string, sessionId: string, since: number): FreshHandoff | null;
|
|
56
|
+
/**
|
|
57
|
+
* The reload text for a session that fired and then compacted, or null when there is nothing to bring
|
|
58
|
+
* back. `allowFired` lets SessionStart (source "compact") reload even when PostCompact has not run yet.
|
|
59
|
+
* The record moves to "reloaded" first, so the excerpt is injected once.
|
|
60
|
+
*/
|
|
61
|
+
export declare function takeReloadContext(repoRoot: string, sessionId: string, env: NodeJS.ProcessEnv, allowFired: boolean): string | null;
|
|
62
|
+
/** Mirror of the rendered state for the doctor: what this session's record says. */
|
|
63
|
+
export declare function readSessionPhase(repoRoot: string, sessionId: string): AutoHandoffPhase | null;
|
|
64
|
+
export {};
|