tokenusage-cli 0.1.0 → 0.2.1

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.
Files changed (131) hide show
  1. package/CHANGELOG.md +46 -19
  2. package/LICENSE +22 -22
  3. package/README.md +123 -94
  4. package/THIRD_PARTY_NOTICES.md +140 -140
  5. package/bin/tokenusage.js +69 -69
  6. package/package.json +59 -59
  7. package/src/cli.js +146 -134
  8. package/src/commands/device-login.js +205 -205
  9. package/src/commands/diagnostics.js +38 -38
  10. package/src/commands/doctor.js +110 -110
  11. package/src/commands/init.js +2484 -2436
  12. package/src/commands/pause.js +77 -0
  13. package/src/commands/sessions.js +29 -29
  14. package/src/commands/status.js +1758 -1747
  15. package/src/commands/sync.js +8048 -7934
  16. package/src/commands/uninstall.js +322 -312
  17. package/src/lib/account-usage-dedup.js +267 -267
  18. package/src/lib/antigravity-paths.js +48 -48
  19. package/src/lib/ark-agent-plan-limits.js +438 -438
  20. package/src/lib/ark-coding-plan-limits.js +537 -537
  21. package/src/lib/async-queue-reader.js +138 -138
  22. package/src/lib/atomic-json.js +27 -27
  23. package/src/lib/bearer-token.js +11 -11
  24. package/src/lib/categorizer-utils.js +232 -232
  25. package/src/lib/claude-categorizer.js +1343 -1343
  26. package/src/lib/claude-config.js +279 -279
  27. package/src/lib/claude-user-identity.js +56 -56
  28. package/src/lib/cli-ui.js +179 -179
  29. package/src/lib/cloud-account.js +541 -541
  30. package/src/lib/cloud-device-token.js +141 -141
  31. package/src/lib/cloud-sync-prefs.js +14 -14
  32. package/src/lib/cloud-usage-reset.js +115 -115
  33. package/src/lib/codex-config.js +595 -595
  34. package/src/lib/codex-context-breakdown.js +806 -806
  35. package/src/lib/codex-model-attribution.js +128 -128
  36. package/src/lib/codex-rollout-parser.js +1471 -1471
  37. package/src/lib/codex-service-tier.js +49 -49
  38. package/src/lib/codex-token-refresh.js +140 -140
  39. package/src/lib/codex-token-usage.js +195 -195
  40. package/src/lib/codex-usage-record.js +195 -195
  41. package/src/lib/collection-pause.js +77 -0
  42. package/src/lib/command-runner.js +313 -313
  43. package/src/lib/commandcode-limits.js +317 -317
  44. package/src/lib/context-health.js +124 -124
  45. package/src/lib/cursor-config.js +605 -605
  46. package/src/lib/cursor-store.js +1918 -1918
  47. package/src/lib/debug-flags.js +7 -7
  48. package/src/lib/devin-limits.js +249 -249
  49. package/src/lib/devin-usage.js +212 -212
  50. package/src/lib/diagnostics.js +383 -383
  51. package/src/lib/doctor.js +385 -385
  52. package/src/lib/dumate.js +95 -95
  53. package/src/lib/fs.js +455 -455
  54. package/src/lib/function-url.js +14 -14
  55. package/src/lib/gemini-config.js +291 -291
  56. package/src/lib/git-outcomes.js +243 -243
  57. package/src/lib/grok-context-breakdown.js +890 -890
  58. package/src/lib/grok-hook.js +360 -360
  59. package/src/lib/grok-limits.js +865 -865
  60. package/src/lib/grok-usage.js +98 -98
  61. package/src/lib/heatmap-compact.js +114 -114
  62. package/src/lib/ingest-sanitize.js +41 -41
  63. package/src/lib/init-flow.js +42 -42
  64. package/src/lib/install-resolver.js +170 -170
  65. package/src/lib/jsonl-lines.js +134 -134
  66. package/src/lib/kimi-model-repair.js +173 -173
  67. package/src/lib/kimi-profile.js +61 -61
  68. package/src/lib/kimi-session.js +216 -216
  69. package/src/lib/local-api.js +3588 -3588
  70. package/src/lib/machine-id.js +238 -238
  71. package/src/lib/multi-install-parser.js +113 -113
  72. package/src/lib/notify-command.js +38 -38
  73. package/src/lib/omp-hook.js +589 -589
  74. package/src/lib/openclaw-cli.js +104 -104
  75. package/src/lib/openclaw-hook.js +375 -375
  76. package/src/lib/openclaw-session-plugin.js +560 -560
  77. package/src/lib/opencode-config.js +121 -121
  78. package/src/lib/opencode-go-limits.js +807 -807
  79. package/src/lib/outcomes-engine.js +253 -253
  80. package/src/lib/passive-mode.js +219 -219
  81. package/src/lib/pet-packages.js +722 -722
  82. package/src/lib/pricing/curated-overrides.json +822 -822
  83. package/src/lib/pricing/index.js +379 -379
  84. package/src/lib/pricing/litellm-fetcher.js +172 -172
  85. package/src/lib/pricing/matcher.js +456 -456
  86. package/src/lib/pricing/seed-snapshot.json +1 -1
  87. package/src/lib/progress.js +76 -76
  88. package/src/lib/project-usage-purge.js +117 -117
  89. package/src/lib/prompt.js +24 -24
  90. package/src/lib/provider-status.js +104 -104
  91. package/src/lib/proxy-env.js +489 -489
  92. package/src/lib/proxy-settings.js +163 -163
  93. package/src/lib/qoder-cn-cli-limits.js +119 -119
  94. package/src/lib/qoder-limits.js +880 -880
  95. package/src/lib/quiet-warnings.js +26 -26
  96. package/src/lib/rollout.js +26005 -25966
  97. package/src/lib/runtime-config.js +9 -4
  98. package/src/lib/scan-roots.js +277 -277
  99. package/src/lib/scheduled-task.js +145 -0
  100. package/src/lib/sentry.js +231 -231
  101. package/src/lib/session-analytics.js +2972 -2972
  102. package/src/lib/session-performance.js +237 -237
  103. package/src/lib/session-upload.js +379 -379
  104. package/src/lib/skill-usage.js +267 -267
  105. package/src/lib/skills-manager.js +1591 -1591
  106. package/src/lib/source-metadata.js +48 -48
  107. package/src/lib/sqlite-reader.js +215 -215
  108. package/src/lib/star-cta.js +73 -73
  109. package/src/lib/subscription-manager.js +293 -293
  110. package/src/lib/subscriptions.js +508 -508
  111. package/src/lib/sync-report.js +138 -0
  112. package/src/lib/telemetry.js +193 -193
  113. package/src/lib/tracker-paths.js +16 -16
  114. package/src/lib/trae-cn-config.js +548 -548
  115. package/src/lib/trae-db.js +127 -127
  116. package/src/lib/trae-snapshot.js +230 -230
  117. package/src/lib/trae-sqlite.js +143 -143
  118. package/src/lib/trae-usage.js +121 -121
  119. package/src/lib/upload-queue.js +134 -134
  120. package/src/lib/upload-throttle.js +171 -171
  121. package/src/lib/usage-limits.js +4552 -4552
  122. package/src/lib/wrapped-aggregator.js +236 -236
  123. package/src/lib/wsl-probe.js +281 -281
  124. package/src/lib/zcode-limits.js +1172 -1172
  125. package/src/lib/zcode-reset-credits.js +66 -66
  126. package/test/audit-fixes.test.js +200 -0
  127. package/test/cli-smoke.test.js +53 -53
  128. package/test/collection-controls.test.js +210 -0
  129. package/test/ingest-sanitize.test.js +162 -162
  130. package/test/quiet-warnings.test.js +53 -53
  131. package/test/session-upload.test.js +427 -427
@@ -1,722 +1,722 @@
1
- const fs = require("node:fs");
2
- const os = require("node:os");
3
- const path = require("node:path");
4
- const crypto = require("node:crypto");
5
- const yauzl = require("yauzl");
6
-
7
- const PET_MANIFEST = "pet.json";
8
- const PET_SPRITESHEET = "spritesheet.webp";
9
- const MAX_PACKAGE_BYTES = 12 * 1024 * 1024;
10
- const MAX_MANIFEST_BYTES = 16 * 1024;
11
- const MAX_SPRITESHEET_BYTES = 10 * 1024 * 1024;
12
- // `bot` joins clawd as a built-in with no sprite atlas: it is drawn from the
13
- // vector engine in dashboard/src/lib/bot/, so it costs no disk space and is
14
- // therefore not in REMOVABLE_BUILTIN_IDS — that list exists to reclaim the
15
- // space an atlas takes.
16
- const BUILTIN_IDS = new Set(["clawd", "bot", "sprout", "byte", "ember"]);
17
- const REMOVABLE_BUILTIN_IDS = new Set(["sprout", "byte", "ember"]);
18
- const HIDDEN_BUILTINS_FILE = ".hidden-builtins.json";
19
- // codex-pets.net added `kind` to pet.json long after launch, and its enum may keep
20
- // growing — packages published before that (and future kinds) must stay importable,
21
- // so kind is optional metadata validated only as a short slug.
22
- const KIND_RE = /^[a-z][a-z0-9-]{0,39}$/;
23
- const PET_ID_RE = /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/;
24
- const petDirectoryCache = new Map();
25
- let codexAsarCache = null;
26
-
27
- // Token Usage keeps its own pets under ~/.tokenusage/pets and never writes to the
28
- // Codex app: URL/zip imports stay here, and Codex is only ever read from (reverse
29
- // import). `~/.codex/pets` is reachable purely as an import source.
30
- const MIGRATION_MARKER = ".migrated-v1";
31
-
32
- function resolvePetsDir() {
33
- return path.resolve(
34
- process.env.TOKENUSAGE_PETS_DIR || path.join(os.homedir(), ".tokenusage", "pets"),
35
- );
36
- }
37
-
38
- function resolveCodexPetsDir() {
39
- return path.resolve(
40
- process.env.TOKENUSAGE_CODEX_PETS_DIR || path.join(os.homedir(), ".codex", "pets"),
41
- );
42
- }
43
-
44
- function readHiddenBuiltinIds() {
45
- const file = path.join(resolvePetsDir(), HIDDEN_BUILTINS_FILE);
46
- try {
47
- const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
48
- if (!Array.isArray(parsed)) return [];
49
- return [...new Set(parsed
50
- .map((id) => String(id || "").trim().toLowerCase())
51
- .filter((id) => REMOVABLE_BUILTIN_IDS.has(id)))].sort();
52
- } catch {
53
- return [];
54
- }
55
- }
56
-
57
- function hideBuiltinPet(id) {
58
- const normalized = String(id || "").trim().toLowerCase();
59
- if (normalized === "clawd") throw new Error("Clawd cannot be removed");
60
- if (!REMOVABLE_BUILTIN_IDS.has(normalized)) throw new Error("Invalid built-in pet id");
61
-
62
- const root = resolvePetsDir();
63
- fs.mkdirSync(root, { recursive: true, mode: 0o700 });
64
- const hidden = new Set(readHiddenBuiltinIds());
65
- hidden.add(normalized);
66
- const destination = path.join(root, HIDDEN_BUILTINS_FILE);
67
- const stage = path.join(root, `${HIDDEN_BUILTINS_FILE}.${process.pid}-${crypto.randomBytes(6).toString("hex")}`);
68
- const backup = `${stage}-backup`;
69
- try {
70
- fs.writeFileSync(stage, `${JSON.stringify([...hidden].sort(), null, 2)}\n`, { mode: 0o600 });
71
- if (fs.existsSync(destination)) fs.renameSync(destination, backup);
72
- fs.renameSync(stage, destination);
73
- } catch (error) {
74
- try { fs.rmSync(stage, { force: true }); } catch {}
75
- if (!fs.existsSync(destination) && fs.existsSync(backup)) fs.renameSync(backup, destination);
76
- throw error;
77
- }
78
- try { fs.rmSync(backup, { force: true }); } catch {}
79
- return { id: normalized, hidden: true };
80
- }
81
-
82
- function readUInt24LE(buffer, offset) {
83
- return buffer[offset] | (buffer[offset + 1] << 8) | (buffer[offset + 2] << 16);
84
- }
85
-
86
- function readWebpDimensions(buffer) {
87
- if (
88
- !Buffer.isBuffer(buffer)
89
- || buffer.length < 30
90
- || buffer.subarray(0, 4).toString("ascii") !== "RIFF"
91
- || buffer.subarray(8, 12).toString("ascii") !== "WEBP"
92
- ) {
93
- throw new Error("spritesheet.webp is not a valid WebP file");
94
- }
95
- if (buffer.readUInt32LE(4) + 8 !== buffer.length) {
96
- throw new Error("spritesheet.webp has an invalid RIFF size");
97
- }
98
-
99
- let offset = 12;
100
- while (offset + 8 <= buffer.length) {
101
- const type = buffer.subarray(offset, offset + 4).toString("ascii");
102
- const size = buffer.readUInt32LE(offset + 4);
103
- const data = offset + 8;
104
- if (data + size > buffer.length) throw new Error("spritesheet.webp is truncated");
105
- if (type === "VP8X" && size >= 10) {
106
- return {
107
- width: readUInt24LE(buffer, data + 4) + 1,
108
- height: readUInt24LE(buffer, data + 7) + 1,
109
- };
110
- }
111
- if (type === "VP8 " && size >= 10) {
112
- if (buffer[data + 3] !== 0x9d || buffer[data + 4] !== 0x01 || buffer[data + 5] !== 0x2a) {
113
- throw new Error("spritesheet.webp has an invalid VP8 frame header");
114
- }
115
- return {
116
- width: buffer.readUInt16LE(data + 6) & 0x3fff,
117
- height: buffer.readUInt16LE(data + 8) & 0x3fff,
118
- };
119
- }
120
- if (type === "VP8L" && size >= 5) {
121
- if (buffer[data] !== 0x2f) throw new Error("spritesheet.webp has an invalid VP8L header");
122
- const bits = buffer.readUInt32LE(data + 1);
123
- return { width: (bits & 0x3fff) + 1, height: ((bits >>> 14) & 0x3fff) + 1 };
124
- }
125
- offset = data + size + (size % 2);
126
- }
127
- throw new Error("spritesheet.webp has no decodable image frame");
128
- }
129
-
130
- function normalizeManifest(value) {
131
- if (!value || typeof value !== "object" || Array.isArray(value)) {
132
- throw new Error("pet.json must contain a JSON object");
133
- }
134
- const id = String(value.id || "").trim().toLowerCase();
135
- const displayName = String(value.displayName || "").trim();
136
- const description = String(value.description || "").trim();
137
- const spritesheetPath = String(value.spritesheetPath || "").trim();
138
- const kind = String(value.kind || "").trim().toLowerCase();
139
- const versionProvided = value.spriteVersionNumber !== undefined;
140
- const spriteVersionNumber = versionProvided ? value.spriteVersionNumber : 1;
141
-
142
- if (!PET_ID_RE.test(id)) throw new Error("pet.json id must be a lowercase URL-safe slug");
143
- if (BUILTIN_IDS.has(id)) throw new Error(`${id} is reserved by a built-in Token Usage pet`);
144
- if (!displayName || displayName.length > 80) throw new Error("pet.json displayName is required and must be at most 80 characters");
145
- if (!description || description.length > 280) throw new Error("pet.json description is required and must be at most 280 characters");
146
- if (spritesheetPath !== PET_SPRITESHEET) throw new Error("pet.json spritesheetPath must be spritesheet.webp");
147
- if (kind && !KIND_RE.test(kind)) throw new Error("pet.json kind must be a short lowercase label when provided");
148
- if (versionProvided && spriteVersionNumber !== 2) {
149
- throw new Error("pet.json spriteVersionNumber must be 2 when provided");
150
- }
151
-
152
- return {
153
- id,
154
- displayName,
155
- description,
156
- spritesheetPath: PET_SPRITESHEET,
157
- spriteVersionNumber,
158
- ...(kind ? { kind } : {}),
159
- };
160
- }
161
-
162
- function validatePackageFiles(manifestBuffer, spritesheetBuffer) {
163
- if (!Buffer.isBuffer(manifestBuffer) || manifestBuffer.length === 0 || manifestBuffer.length > MAX_MANIFEST_BYTES) {
164
- throw new Error("pet.json is missing or too large");
165
- }
166
- if (!Buffer.isBuffer(spritesheetBuffer) || spritesheetBuffer.length === 0 || spritesheetBuffer.length > MAX_SPRITESHEET_BYTES) {
167
- throw new Error("spritesheet.webp is missing or too large");
168
- }
169
-
170
- let parsed;
171
- try {
172
- parsed = JSON.parse(manifestBuffer.toString("utf8"));
173
- } catch {
174
- throw new Error("pet.json is not valid JSON");
175
- }
176
- const manifest = normalizeManifest(parsed);
177
- const dimensions = readWebpDimensions(spritesheetBuffer);
178
- const expectedHeight = manifest.spriteVersionNumber === 2 ? 2288 : 1872;
179
- if (dimensions.width !== 1536 || dimensions.height !== expectedHeight) {
180
- throw new Error(
181
- `spritesheet.webp must be 1536x${expectedHeight} for a v${manifest.spriteVersionNumber} pet`,
182
- );
183
- }
184
- return { manifest, dimensions };
185
- }
186
-
187
- function readZipEntries(zipBuffer) {
188
- if (!Buffer.isBuffer(zipBuffer) || zipBuffer.length === 0 || zipBuffer.length > MAX_PACKAGE_BYTES) {
189
- return Promise.reject(new Error("Pet package is empty or exceeds 12 MB"));
190
- }
191
- return new Promise((resolve, reject) => {
192
- yauzl.fromBuffer(zipBuffer, { lazyEntries: true, validateEntrySizes: true }, (openError, zipfile) => {
193
- if (openError) return reject(new Error(`Invalid pet package: ${openError.message}`));
194
- const entries = new Map();
195
- let settled = false;
196
- const fail = (error) => {
197
- if (settled) return;
198
- settled = true;
199
- try { zipfile.close(); } catch {}
200
- reject(error);
201
- };
202
- zipfile.on("error", (error) => fail(new Error(`Invalid pet package: ${error.message}`)));
203
- zipfile.on("entry", (entry) => {
204
- const name = String(entry.fileName || "");
205
- const unixMode = (entry.externalFileAttributes >>> 16) & 0xffff;
206
- if ((unixMode & 0xf000) === 0xa000) {
207
- fail(new Error("Pet package entries must not be symbolic links"));
208
- return;
209
- }
210
- if (name !== PET_MANIFEST && name !== PET_SPRITESHEET) {
211
- fail(new Error("A standard pet package must contain only pet.json and spritesheet.webp at its root"));
212
- return;
213
- }
214
- if (entries.has(name)) {
215
- fail(new Error(`Pet package contains duplicate ${name}`));
216
- return;
217
- }
218
- const limit = name === PET_MANIFEST ? MAX_MANIFEST_BYTES : MAX_SPRITESHEET_BYTES;
219
- if (entry.uncompressedSize <= 0 || entry.uncompressedSize > limit) {
220
- fail(new Error(`${name} is empty or too large`));
221
- return;
222
- }
223
- zipfile.openReadStream(entry, (streamError, stream) => {
224
- if (streamError) return fail(new Error(`Could not read ${name}: ${streamError.message}`));
225
- const chunks = [];
226
- let total = 0;
227
- stream.on("data", (chunk) => {
228
- total += chunk.length;
229
- if (total > limit) {
230
- stream.destroy(new Error(`${name} is too large`));
231
- return;
232
- }
233
- chunks.push(chunk);
234
- });
235
- stream.on("error", (error) => fail(error));
236
- stream.on("end", () => {
237
- if (settled) return;
238
- entries.set(name, Buffer.concat(chunks));
239
- zipfile.readEntry();
240
- });
241
- });
242
- });
243
- zipfile.on("end", () => {
244
- if (settled) return;
245
- settled = true;
246
- if (entries.size !== 2 || !entries.has(PET_MANIFEST) || !entries.has(PET_SPRITESHEET)) {
247
- reject(new Error("Pet package must contain pet.json and spritesheet.webp"));
248
- return;
249
- }
250
- resolve(entries);
251
- });
252
- zipfile.readEntry();
253
- });
254
- });
255
- }
256
-
257
- function publicPet(manifest, extra = {}) {
258
- const assetVersion = extra.assetVersion || "";
259
- return {
260
- ...manifest,
261
- custom: true,
262
- assetUrl: `/api/pets/local/${encodeURIComponent(manifest.id)}/${PET_SPRITESHEET}${assetVersion ? `?v=${encodeURIComponent(assetVersion)}` : ""}`,
263
- ...extra,
264
- };
265
- }
266
-
267
- function loadPetDirectory(directory, expectedId = null) {
268
- const stat = fs.lstatSync(directory);
269
- if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error("Pet path is not a directory");
270
- const manifestPath = path.join(directory, PET_MANIFEST);
271
- const spritesheetPath = path.join(directory, PET_SPRITESHEET);
272
- const manifestStat = fs.lstatSync(manifestPath);
273
- const spriteStat = fs.lstatSync(spritesheetPath);
274
- if (!manifestStat.isFile() || manifestStat.isSymbolicLink() || !spriteStat.isFile() || spriteStat.isSymbolicLink()) {
275
- throw new Error("Pet assets must be regular files");
276
- }
277
- if (manifestStat.size <= 0 || manifestStat.size > MAX_MANIFEST_BYTES) {
278
- throw new Error("pet.json is missing or too large");
279
- }
280
- if (spriteStat.size <= 0 || spriteStat.size > MAX_SPRITESHEET_BYTES) {
281
- throw new Error("spritesheet.webp is missing or too large");
282
- }
283
- const cacheKey = [
284
- manifestStat.mtimeMs,
285
- manifestStat.size,
286
- spriteStat.mtimeMs,
287
- spriteStat.size,
288
- ].join(":");
289
- const cacheId = directory;
290
- const cached = petDirectoryCache.get(cacheId);
291
- if (cached?.cacheKey === cacheKey) return cached.value;
292
- const result = validatePackageFiles(fs.readFileSync(manifestPath), fs.readFileSync(spritesheetPath));
293
- if (expectedId && result.manifest.id !== expectedId) throw new Error("Pet directory and manifest id do not match");
294
- const value = {
295
- ...result,
296
- directory,
297
- spritesheetPath,
298
- assetVersion: `${Math.trunc(spriteStat.mtimeMs)}-${spriteStat.size}`,
299
- };
300
- petDirectoryCache.set(cacheId, { cacheKey, value });
301
- return value;
302
- }
303
-
304
- /**
305
- * Move third-party packages out of directories whose id we have since reserved.
306
- *
307
- * `bot` became a built-in in 0.93.0. A user who had imported a package with that id
308
- * would otherwise lose it silently: BUILTIN_IDS skips it in every listing, and
309
- * removeInstalledPet routes it to hideBuiltinPet, which rejects a non-removable
310
- * built-in — so the directory became invisible AND undeletable, up to 10 MB of it.
311
- *
312
- * Renaming keeps the package usable instead of just deleting it. Idempotent by
313
- * construction: after the rename the reserved path no longer exists. If the manifest
314
- * rewrite fails mid-way the package is unusable but freely removable, which still
315
- * beats the state above.
316
- */
317
- function reclaimReservedPetDirectories(root) {
318
- for (const reserved of BUILTIN_IDS) {
319
- const source = path.join(root, reserved);
320
- if (!fs.existsSync(path.join(source, PET_MANIFEST))) continue;
321
- let target = `${reserved}-imported`;
322
- for (let suffix = 2; fs.existsSync(path.join(root, target)); suffix += 1) {
323
- target = `${reserved}-imported-${suffix}`;
324
- }
325
- try {
326
- fs.renameSync(source, path.join(root, target));
327
- } catch {
328
- continue;
329
- }
330
- // The manifest id must match the directory name or the package fails to load.
331
- const manifestPath = path.join(root, target, PET_MANIFEST);
332
- try {
333
- const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
334
- manifest.id = target;
335
- fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
336
- } catch {
337
- // Left unusable but removable; nothing else to do here.
338
- }
339
- }
340
- }
341
-
342
- function listInstalledPets() {
343
- migrateLegacyCodexPets();
344
- const root = resolvePetsDir();
345
- reclaimReservedPetDirectories(root);
346
- let names = [];
347
- try { names = fs.readdirSync(root); } catch (error) {
348
- if (error?.code === "ENOENT") return [];
349
- throw error;
350
- }
351
- const pets = [];
352
- for (const name of names) {
353
- if (!PET_ID_RE.test(name) || BUILTIN_IDS.has(name)) continue;
354
- try {
355
- const loaded = loadPetDirectory(path.join(root, name), name);
356
- pets.push(publicPet(loaded.manifest, { assetVersion: loaded.assetVersion }));
357
- } catch {
358
- // Invalid or partially copied directories are ignored until they become valid.
359
- }
360
- }
361
- return pets.sort((a, b) => a.displayName.localeCompare(b.displayName));
362
- }
363
-
364
- // Atomically writes one validated pet into `root` (staged dir → rename), optionally
365
- // dropping `markerName` inside the pet directory. Returns the loaded asset info.
366
- function writePetIntoDir(root, manifest, spritesheetBuffer, markerName = null) {
367
- fs.mkdirSync(root, { recursive: true, mode: 0o700 });
368
- const stage = path.join(root, `.tokenusage-pet-${process.pid}-${crypto.randomBytes(6).toString("hex")}`);
369
- const destination = path.join(root, manifest.id);
370
- const backup = `${stage}-backup`;
371
- fs.mkdirSync(stage, { mode: 0o700 });
372
- try {
373
- fs.writeFileSync(path.join(stage, PET_MANIFEST), `${JSON.stringify({
374
- id: manifest.id,
375
- displayName: manifest.displayName,
376
- description: manifest.description,
377
- spritesheetPath: PET_SPRITESHEET,
378
- ...(manifest.spriteVersionNumber === 2 ? { spriteVersionNumber: 2 } : {}),
379
- kind: manifest.kind,
380
- }, null, 2)}\n`, { mode: 0o600 });
381
- fs.writeFileSync(path.join(stage, PET_SPRITESHEET), spritesheetBuffer, { mode: 0o600 });
382
- if (markerName) fs.writeFileSync(path.join(stage, markerName), "", { mode: 0o600 });
383
- loadPetDirectory(stage, manifest.id);
384
- petDirectoryCache.delete(destination);
385
- if (fs.existsSync(destination)) fs.renameSync(destination, backup);
386
- fs.renameSync(stage, destination);
387
- petDirectoryCache.delete(stage);
388
- } catch (error) {
389
- petDirectoryCache.delete(stage);
390
- fs.rmSync(stage, { recursive: true, force: true });
391
- if (!fs.existsSync(destination) && fs.existsSync(backup)) fs.renameSync(backup, destination);
392
- throw error;
393
- }
394
- try { fs.rmSync(backup, { recursive: true, force: true }); } catch {}
395
- return loadPetDirectory(destination, manifest.id);
396
- }
397
-
398
- function installValidatedPackage(manifestBuffer, spritesheetBuffer) {
399
- const { manifest } = validatePackageFiles(manifestBuffer, spritesheetBuffer);
400
- const installed = writePetIntoDir(resolvePetsDir(), manifest, spritesheetBuffer);
401
- return publicPet(manifest, { assetVersion: installed.assetVersion });
402
- }
403
-
404
- async function importPetZip(zipBuffer) {
405
- const entries = await readZipEntries(zipBuffer);
406
- return installValidatedPackage(entries.get(PET_MANIFEST), entries.get(PET_SPRITESHEET));
407
- }
408
-
409
- function petIdFromCodexPetsUrl(input) {
410
- const raw = String(input || "").trim();
411
- if (PET_ID_RE.test(raw)) return raw;
412
- let parsed;
413
- try { parsed = new URL(raw); } catch { throw new Error("Enter a Codex Pets URL or pet id"); }
414
- if (parsed.protocol !== "https:" || parsed.hostname !== "codex-pets.net") {
415
- throw new Error("Only https://codex-pets.net pet URLs are supported");
416
- }
417
- const hashMatch = parsed.hash.match(/^#\/pets\/([a-z0-9-]+)\/?$/i);
418
- const pathMatch = parsed.pathname.match(/^\/api\/pets\/([a-z0-9-]+)(?:\/download)?\/?$/i);
419
- const id = String(hashMatch?.[1] || pathMatch?.[1] || "").toLowerCase();
420
- if (!PET_ID_RE.test(id)) throw new Error("The Codex Pets URL does not contain a valid pet id");
421
- return id;
422
- }
423
-
424
- async function installFromCodexPets(input, fetchImpl = fetch) {
425
- const id = petIdFromCodexPetsUrl(input);
426
- const controller = new AbortController();
427
- const timeout = setTimeout(() => controller.abort(), 30_000);
428
- timeout.unref?.();
429
- try {
430
- const response = await fetchImpl(`https://codex-pets.net/api/pets/${encodeURIComponent(id)}/download`, {
431
- redirect: "follow",
432
- signal: controller.signal,
433
- headers: { accept: "application/zip", "user-agent": "tokenusage-cli Pet Importer" },
434
- });
435
- if (!response.ok) throw new Error(`Codex Pets download failed with HTTP ${response.status}`);
436
- const length = Number(response.headers.get("content-length") || 0);
437
- if (length > MAX_PACKAGE_BYTES) throw new Error("Pet package exceeds 12 MB");
438
- const chunks = [];
439
- let total = 0;
440
- for await (const chunk of response.body || []) {
441
- total += chunk.length;
442
- if (total > MAX_PACKAGE_BYTES) throw new Error("Pet package exceeds 12 MB");
443
- chunks.push(Buffer.from(chunk));
444
- }
445
- const body = Buffer.concat(chunks);
446
- return await importPetZip(body);
447
- } finally {
448
- clearTimeout(timeout);
449
- }
450
- }
451
-
452
- function removeInstalledPet(id) {
453
- const normalized = String(id || "").trim().toLowerCase();
454
- if (!PET_ID_RE.test(normalized)) throw new Error("Invalid pet id");
455
- if (BUILTIN_IDS.has(normalized)) return hideBuiltinPet(normalized);
456
- const root = resolvePetsDir();
457
- const destination = path.join(root, normalized);
458
- if (!destination.startsWith(`${root}${path.sep}`)) throw new Error("Invalid pet path");
459
- fs.rmSync(destination, { recursive: true, force: true });
460
- petDirectoryCache.delete(destination);
461
- return { id: normalized };
462
- }
463
-
464
- function resolvePetAsset(id) {
465
- // Native hosts can ask for the persisted custom pet before the dashboard has
466
- // listed the catalog. Migrate first so an upgrade does not turn that first
467
- // request into a 404 and reset the user's selection.
468
- migrateLegacyCodexPets();
469
- const normalized = String(id || "").trim().toLowerCase();
470
- if (!PET_ID_RE.test(normalized) || BUILTIN_IDS.has(normalized)) return null;
471
- try { return loadPetDirectory(path.join(resolvePetsDir(), normalized), normalized); } catch { return null; }
472
- }
473
-
474
- // --- One-time migration: copy legacy pets out of the shared Codex dir into our own ---
475
-
476
- function migrateLegacyCodexPets() {
477
- const root = resolvePetsDir();
478
- const marker = path.join(root, MIGRATION_MARKER);
479
- try { if (fs.existsSync(marker)) return { migrated: 0 }; } catch { return { migrated: 0 }; }
480
- try { fs.mkdirSync(root, { recursive: true, mode: 0o700 }); } catch { return { migrated: 0 }; }
481
- let migrated = 0;
482
- let names = [];
483
- let scanComplete = false;
484
- try {
485
- names = fs.readdirSync(resolveCodexPetsDir());
486
- scanComplete = true;
487
- } catch (error) {
488
- // A missing legacy directory is a completed no-op. Permission and I/O
489
- // failures are not: leave the marker absent so the next launch can retry.
490
- if (error?.code === "ENOENT") scanComplete = true;
491
- }
492
- let copyFailed = false;
493
- for (const name of names) {
494
- if (!PET_ID_RE.test(name) || BUILTIN_IDS.has(name)) continue;
495
- if (fs.existsSync(path.join(root, name))) continue; // never clobber an existing local pet
496
- let loaded;
497
- try {
498
- loaded = loadPetDirectory(path.join(resolveCodexPetsDir(), name), name);
499
- } catch {
500
- // Invalid legacy packages are ignored just as they were by the old catalog.
501
- continue;
502
- }
503
- try {
504
- writePetIntoDir(root, loaded.manifest, fs.readFileSync(loaded.spritesheetPath));
505
- migrated += 1;
506
- } catch {
507
- copyFailed = true;
508
- }
509
- }
510
- if (scanComplete && !copyFailed) {
511
- try { fs.writeFileSync(marker, `${new Date().toISOString()}\n`, { mode: 0o600 }); } catch {}
512
- }
513
- return { migrated };
514
- }
515
-
516
- // --- Reverse import: pull Codex's own pets into Token Usage ---
517
-
518
- // Resolved per call (not frozen at load) so an env override applies at runtime.
519
- function resolveCodexAsarPath() {
520
- return process.env.TOKENUSAGE_CODEX_ASAR
521
- || "/Applications/Codex.app/Contents/Resources/app.asar";
522
- }
523
- // Codex ships these native companions bundled inside its app; the display names are
524
- // stable brand labels. Anything not listed falls back to a capitalized id.
525
- const CODEX_BUILTIN_NAMES = {
526
- rocky: "Rocky", seedy: "Seedy", hoots: "Hoots", dewey: "Dewey", fireball: "Fireball",
527
- stacky: "Stacky", codex: "Codex", bsod: "BSOD", "null-signal": "Null Signal",
528
- };
529
-
530
- // Parses the asar header (Chromium Pickle) and returns the file tree plus the byte
531
- // offset where file contents begin. Pure Node, no dependency — asar's layout is stable.
532
- function readAsarHeader(fd) {
533
- const head = Buffer.alloc(16);
534
- if (fs.readSync(fd, head, 0, 16, 0) < 16) throw new Error("asar too small");
535
- const headerPayloadSize = head.readUInt32LE(4);
536
- const jsonStrLen = head.readUInt32LE(12);
537
- if (jsonStrLen <= 0 || jsonStrLen > 64 * 1024 * 1024) throw new Error("asar header size out of range");
538
- const jsonBuf = Buffer.alloc(jsonStrLen);
539
- fs.readSync(fd, jsonBuf, 0, jsonStrLen, 16);
540
- const header = JSON.parse(jsonBuf.toString("utf8"));
541
- const base = 8 + headerPayloadSize;
542
- return { header, baseOffset: base % 4 ? base + 4 - (base % 4) : base };
543
- }
544
-
545
- // Reads Codex's bundled companion spritesheets out of the app's asar. Returns
546
- // [{ id, displayName, description, spriteVersionNumber, buffer }]. Degrades to [] if
547
- // Codex isn't installed or the bundle can't be read.
548
- function readCodexBuiltinPets(asarPath = resolveCodexAsarPath()) {
549
- const resolvedAsarPath = path.resolve(asarPath);
550
- let asarStat;
551
- try { asarStat = fs.statSync(resolvedAsarPath); } catch { return []; }
552
- const cacheKey = `${resolvedAsarPath}:${asarStat.mtimeMs}:${asarStat.size}`;
553
- if (codexAsarCache?.key === cacheKey) return codexAsarCache.pets;
554
-
555
- let fd;
556
- try { fd = fs.openSync(resolvedAsarPath, "r"); } catch { return []; }
557
- try {
558
- const { header, baseOffset } = readAsarHeader(fd);
559
- const entries = [];
560
- (function walk(node) {
561
- for (const [name, value] of Object.entries(node?.files || {})) {
562
- if (value?.files) walk(value);
563
- else if (/-spritesheet-.*\.webp$/i.test(name) && value?.offset != null) entries.push([name, value]);
564
- }
565
- })(header);
566
- const byId = new Map();
567
- for (const [name, entry] of entries) {
568
- const id = name.replace(/-spritesheet-.*$/i, "").toLowerCase();
569
- if (!PET_ID_RE.test(id) || BUILTIN_IDS.has(id) || byId.has(id)) continue;
570
- const size = Number(entry.size);
571
- if (!(size > 0) || size > MAX_SPRITESHEET_BYTES) continue;
572
- const buffer = Buffer.alloc(size);
573
- fs.readSync(fd, buffer, 0, size, baseOffset + Number(entry.offset));
574
- let dimensions;
575
- try { dimensions = readWebpDimensions(buffer); } catch { continue; }
576
- const spriteVersionNumber = dimensions.width === 1536 && dimensions.height === 2288 ? 2
577
- : dimensions.width === 1536 && dimensions.height === 1872 ? 1 : 0;
578
- if (!spriteVersionNumber) continue;
579
- byId.set(id, {
580
- id,
581
- displayName: CODEX_BUILTIN_NAMES[id] || (id.charAt(0).toUpperCase() + id.slice(1)),
582
- description: "Built-in Codex companion.",
583
- spriteVersionNumber,
584
- buffer,
585
- });
586
- }
587
- const pets = [...byId.values()];
588
- codexAsarCache = { key: cacheKey, pets };
589
- return pets;
590
- } catch {
591
- codexAsarCache = { key: cacheKey, pets: [] };
592
- return [];
593
- }
594
- finally { try { fs.closeSync(fd); } catch {} }
595
- }
596
-
597
- // Preview URL for an importable Codex pet (served before it lands in our own dir).
598
- function codexAssetUrl(id, version) {
599
- return `/api/pets/codex/${encodeURIComponent(id)}/${PET_SPRITESHEET}${version ? `?v=${encodeURIComponent(version)}` : ""}`;
600
- }
601
-
602
- // Lists Codex pets that could be imported but aren't in Token Usage yet: valid
603
- // packages in ~/.codex/pets plus Codex's app-bundled companions. Each carries an
604
- // assetUrl so the picker can preview sprites.
605
- function listCodexImportablePets() {
606
- const alreadyHere = new Set(listInstalledPets().map((pet) => pet.id));
607
- const result = new Map();
608
- const codexRoot = resolveCodexPetsDir();
609
- let names = [];
610
- try { names = fs.readdirSync(codexRoot); } catch { names = []; }
611
- for (const name of names) {
612
- if (!PET_ID_RE.test(name) || BUILTIN_IDS.has(name) || alreadyHere.has(name)) continue;
613
- try {
614
- const loaded = loadPetDirectory(path.join(codexRoot, name), name);
615
- result.set(name, {
616
- ...loaded.manifest,
617
- custom: true,
618
- assetUrl: codexAssetUrl(name, loaded.assetVersion),
619
- assetVersion: loaded.assetVersion,
620
- source: "codex-dir",
621
- });
622
- } catch {}
623
- }
624
- for (const pet of readCodexBuiltinPets()) {
625
- if (alreadyHere.has(pet.id) || result.has(pet.id)) continue;
626
- result.set(pet.id, {
627
- id: pet.id,
628
- displayName: pet.displayName,
629
- description: pet.description,
630
- spritesheetPath: PET_SPRITESHEET,
631
- spriteVersionNumber: pet.spriteVersionNumber,
632
- custom: true,
633
- assetUrl: codexAssetUrl(pet.id, `app${pet.spriteVersionNumber}`),
634
- source: "codex-app",
635
- });
636
- }
637
- return [...result.values()].sort((a, b) => a.displayName.localeCompare(b.displayName));
638
- }
639
-
640
- // Returns { buffer, contentLength } for an importable Codex pet's spritesheet — from
641
- // ~/.codex/pets first, then the app bundle. Powers the picker preview route.
642
- function readCodexImportableAsset(id) {
643
- const normalized = String(id || "").trim().toLowerCase();
644
- if (!PET_ID_RE.test(normalized) || BUILTIN_IDS.has(normalized)) return null;
645
- const codexDir = path.join(resolveCodexPetsDir(), normalized);
646
- try {
647
- const loaded = loadPetDirectory(codexDir, normalized);
648
- return { buffer: fs.readFileSync(loaded.spritesheetPath) };
649
- } catch {}
650
- for (const pet of readCodexBuiltinPets()) {
651
- if (pet.id === normalized) return { buffer: pet.buffer };
652
- }
653
- return null;
654
- }
655
-
656
- function importFromCodex(ids) {
657
- const requested = new Set(
658
- (Array.isArray(ids) ? ids : [])
659
- .map((id) => String(id || "").trim().toLowerCase())
660
- .filter((id) => PET_ID_RE.test(id) && !BUILTIN_IDS.has(id)),
661
- );
662
- if (requested.size === 0) throw new Error("No valid Codex pet ids to import");
663
- const root = resolvePetsDir();
664
- // The listing excludes already-installed ids, but enforce the same rule at
665
- // the write boundary so a handcrafted local API request cannot overwrite a
666
- // Token Usage-owned pet with Codex's copy.
667
- for (const id of [...requested]) {
668
- if (fs.existsSync(path.join(root, id))) requested.delete(id);
669
- }
670
- if (requested.size === 0) throw new Error("Requested Codex pets are already installed");
671
- const codexRoot = resolveCodexPetsDir();
672
- const imported = [];
673
- for (const id of [...requested]) {
674
- try {
675
- const loaded = loadPetDirectory(path.join(codexRoot, id), id);
676
- const installed = writePetIntoDir(root, loaded.manifest, fs.readFileSync(loaded.spritesheetPath));
677
- imported.push(publicPet(loaded.manifest, { assetVersion: installed.assetVersion }));
678
- requested.delete(id);
679
- } catch {}
680
- }
681
- if (requested.size > 0) {
682
- for (const pet of readCodexBuiltinPets()) {
683
- if (!requested.has(pet.id)) continue;
684
- const manifest = normalizeManifest({
685
- id: pet.id,
686
- displayName: pet.displayName,
687
- description: pet.description,
688
- spritesheetPath: PET_SPRITESHEET,
689
- ...(pet.spriteVersionNumber === 2 ? { spriteVersionNumber: 2 } : {}),
690
- });
691
- try {
692
- const installed = writePetIntoDir(root, manifest, pet.buffer);
693
- imported.push(publicPet(manifest, { assetVersion: installed.assetVersion }));
694
- requested.delete(pet.id);
695
- } catch {}
696
- }
697
- }
698
- if (imported.length === 0) throw new Error("None of the requested Codex pets could be imported");
699
- return { imported };
700
- }
701
-
702
- module.exports = {
703
- MAX_PACKAGE_BYTES,
704
- importFromCodex,
705
- importPetZip,
706
- installFromCodexPets,
707
- listCodexImportablePets,
708
- listInstalledPets,
709
- migrateLegacyCodexPets,
710
- normalizeManifest,
711
- petIdFromCodexPetsUrl,
712
- readCodexBuiltinPets,
713
- readCodexImportableAsset,
714
- readHiddenBuiltinIds,
715
- readWebpDimensions,
716
- reclaimReservedPetDirectories,
717
- removeInstalledPet,
718
- resolveCodexPetsDir,
719
- resolvePetAsset,
720
- resolvePetsDir,
721
- validatePackageFiles,
722
- };
1
+ const fs = require("node:fs");
2
+ const os = require("node:os");
3
+ const path = require("node:path");
4
+ const crypto = require("node:crypto");
5
+ const yauzl = require("yauzl");
6
+
7
+ const PET_MANIFEST = "pet.json";
8
+ const PET_SPRITESHEET = "spritesheet.webp";
9
+ const MAX_PACKAGE_BYTES = 12 * 1024 * 1024;
10
+ const MAX_MANIFEST_BYTES = 16 * 1024;
11
+ const MAX_SPRITESHEET_BYTES = 10 * 1024 * 1024;
12
+ // `bot` joins clawd as a built-in with no sprite atlas: it is drawn from the
13
+ // vector engine in dashboard/src/lib/bot/, so it costs no disk space and is
14
+ // therefore not in REMOVABLE_BUILTIN_IDS — that list exists to reclaim the
15
+ // space an atlas takes.
16
+ const BUILTIN_IDS = new Set(["clawd", "bot", "sprout", "byte", "ember"]);
17
+ const REMOVABLE_BUILTIN_IDS = new Set(["sprout", "byte", "ember"]);
18
+ const HIDDEN_BUILTINS_FILE = ".hidden-builtins.json";
19
+ // codex-pets.net added `kind` to pet.json long after launch, and its enum may keep
20
+ // growing — packages published before that (and future kinds) must stay importable,
21
+ // so kind is optional metadata validated only as a short slug.
22
+ const KIND_RE = /^[a-z][a-z0-9-]{0,39}$/;
23
+ const PET_ID_RE = /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/;
24
+ const petDirectoryCache = new Map();
25
+ let codexAsarCache = null;
26
+
27
+ // Token Usage keeps its own pets under ~/.tokenusage/pets and never writes to the
28
+ // Codex app: URL/zip imports stay here, and Codex is only ever read from (reverse
29
+ // import). `~/.codex/pets` is reachable purely as an import source.
30
+ const MIGRATION_MARKER = ".migrated-v1";
31
+
32
+ function resolvePetsDir() {
33
+ return path.resolve(
34
+ process.env.TOKENUSAGE_PETS_DIR || path.join(os.homedir(), ".tokenusage", "pets"),
35
+ );
36
+ }
37
+
38
+ function resolveCodexPetsDir() {
39
+ return path.resolve(
40
+ process.env.TOKENUSAGE_CODEX_PETS_DIR || path.join(os.homedir(), ".codex", "pets"),
41
+ );
42
+ }
43
+
44
+ function readHiddenBuiltinIds() {
45
+ const file = path.join(resolvePetsDir(), HIDDEN_BUILTINS_FILE);
46
+ try {
47
+ const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
48
+ if (!Array.isArray(parsed)) return [];
49
+ return [...new Set(parsed
50
+ .map((id) => String(id || "").trim().toLowerCase())
51
+ .filter((id) => REMOVABLE_BUILTIN_IDS.has(id)))].sort();
52
+ } catch {
53
+ return [];
54
+ }
55
+ }
56
+
57
+ function hideBuiltinPet(id) {
58
+ const normalized = String(id || "").trim().toLowerCase();
59
+ if (normalized === "clawd") throw new Error("Clawd cannot be removed");
60
+ if (!REMOVABLE_BUILTIN_IDS.has(normalized)) throw new Error("Invalid built-in pet id");
61
+
62
+ const root = resolvePetsDir();
63
+ fs.mkdirSync(root, { recursive: true, mode: 0o700 });
64
+ const hidden = new Set(readHiddenBuiltinIds());
65
+ hidden.add(normalized);
66
+ const destination = path.join(root, HIDDEN_BUILTINS_FILE);
67
+ const stage = path.join(root, `${HIDDEN_BUILTINS_FILE}.${process.pid}-${crypto.randomBytes(6).toString("hex")}`);
68
+ const backup = `${stage}-backup`;
69
+ try {
70
+ fs.writeFileSync(stage, `${JSON.stringify([...hidden].sort(), null, 2)}\n`, { mode: 0o600 });
71
+ if (fs.existsSync(destination)) fs.renameSync(destination, backup);
72
+ fs.renameSync(stage, destination);
73
+ } catch (error) {
74
+ try { fs.rmSync(stage, { force: true }); } catch {}
75
+ if (!fs.existsSync(destination) && fs.existsSync(backup)) fs.renameSync(backup, destination);
76
+ throw error;
77
+ }
78
+ try { fs.rmSync(backup, { force: true }); } catch {}
79
+ return { id: normalized, hidden: true };
80
+ }
81
+
82
+ function readUInt24LE(buffer, offset) {
83
+ return buffer[offset] | (buffer[offset + 1] << 8) | (buffer[offset + 2] << 16);
84
+ }
85
+
86
+ function readWebpDimensions(buffer) {
87
+ if (
88
+ !Buffer.isBuffer(buffer)
89
+ || buffer.length < 30
90
+ || buffer.subarray(0, 4).toString("ascii") !== "RIFF"
91
+ || buffer.subarray(8, 12).toString("ascii") !== "WEBP"
92
+ ) {
93
+ throw new Error("spritesheet.webp is not a valid WebP file");
94
+ }
95
+ if (buffer.readUInt32LE(4) + 8 !== buffer.length) {
96
+ throw new Error("spritesheet.webp has an invalid RIFF size");
97
+ }
98
+
99
+ let offset = 12;
100
+ while (offset + 8 <= buffer.length) {
101
+ const type = buffer.subarray(offset, offset + 4).toString("ascii");
102
+ const size = buffer.readUInt32LE(offset + 4);
103
+ const data = offset + 8;
104
+ if (data + size > buffer.length) throw new Error("spritesheet.webp is truncated");
105
+ if (type === "VP8X" && size >= 10) {
106
+ return {
107
+ width: readUInt24LE(buffer, data + 4) + 1,
108
+ height: readUInt24LE(buffer, data + 7) + 1,
109
+ };
110
+ }
111
+ if (type === "VP8 " && size >= 10) {
112
+ if (buffer[data + 3] !== 0x9d || buffer[data + 4] !== 0x01 || buffer[data + 5] !== 0x2a) {
113
+ throw new Error("spritesheet.webp has an invalid VP8 frame header");
114
+ }
115
+ return {
116
+ width: buffer.readUInt16LE(data + 6) & 0x3fff,
117
+ height: buffer.readUInt16LE(data + 8) & 0x3fff,
118
+ };
119
+ }
120
+ if (type === "VP8L" && size >= 5) {
121
+ if (buffer[data] !== 0x2f) throw new Error("spritesheet.webp has an invalid VP8L header");
122
+ const bits = buffer.readUInt32LE(data + 1);
123
+ return { width: (bits & 0x3fff) + 1, height: ((bits >>> 14) & 0x3fff) + 1 };
124
+ }
125
+ offset = data + size + (size % 2);
126
+ }
127
+ throw new Error("spritesheet.webp has no decodable image frame");
128
+ }
129
+
130
+ function normalizeManifest(value) {
131
+ if (!value || typeof value !== "object" || Array.isArray(value)) {
132
+ throw new Error("pet.json must contain a JSON object");
133
+ }
134
+ const id = String(value.id || "").trim().toLowerCase();
135
+ const displayName = String(value.displayName || "").trim();
136
+ const description = String(value.description || "").trim();
137
+ const spritesheetPath = String(value.spritesheetPath || "").trim();
138
+ const kind = String(value.kind || "").trim().toLowerCase();
139
+ const versionProvided = value.spriteVersionNumber !== undefined;
140
+ const spriteVersionNumber = versionProvided ? value.spriteVersionNumber : 1;
141
+
142
+ if (!PET_ID_RE.test(id)) throw new Error("pet.json id must be a lowercase URL-safe slug");
143
+ if (BUILTIN_IDS.has(id)) throw new Error(`${id} is reserved by a built-in Token Usage pet`);
144
+ if (!displayName || displayName.length > 80) throw new Error("pet.json displayName is required and must be at most 80 characters");
145
+ if (!description || description.length > 280) throw new Error("pet.json description is required and must be at most 280 characters");
146
+ if (spritesheetPath !== PET_SPRITESHEET) throw new Error("pet.json spritesheetPath must be spritesheet.webp");
147
+ if (kind && !KIND_RE.test(kind)) throw new Error("pet.json kind must be a short lowercase label when provided");
148
+ if (versionProvided && spriteVersionNumber !== 2) {
149
+ throw new Error("pet.json spriteVersionNumber must be 2 when provided");
150
+ }
151
+
152
+ return {
153
+ id,
154
+ displayName,
155
+ description,
156
+ spritesheetPath: PET_SPRITESHEET,
157
+ spriteVersionNumber,
158
+ ...(kind ? { kind } : {}),
159
+ };
160
+ }
161
+
162
+ function validatePackageFiles(manifestBuffer, spritesheetBuffer) {
163
+ if (!Buffer.isBuffer(manifestBuffer) || manifestBuffer.length === 0 || manifestBuffer.length > MAX_MANIFEST_BYTES) {
164
+ throw new Error("pet.json is missing or too large");
165
+ }
166
+ if (!Buffer.isBuffer(spritesheetBuffer) || spritesheetBuffer.length === 0 || spritesheetBuffer.length > MAX_SPRITESHEET_BYTES) {
167
+ throw new Error("spritesheet.webp is missing or too large");
168
+ }
169
+
170
+ let parsed;
171
+ try {
172
+ parsed = JSON.parse(manifestBuffer.toString("utf8"));
173
+ } catch {
174
+ throw new Error("pet.json is not valid JSON");
175
+ }
176
+ const manifest = normalizeManifest(parsed);
177
+ const dimensions = readWebpDimensions(spritesheetBuffer);
178
+ const expectedHeight = manifest.spriteVersionNumber === 2 ? 2288 : 1872;
179
+ if (dimensions.width !== 1536 || dimensions.height !== expectedHeight) {
180
+ throw new Error(
181
+ `spritesheet.webp must be 1536x${expectedHeight} for a v${manifest.spriteVersionNumber} pet`,
182
+ );
183
+ }
184
+ return { manifest, dimensions };
185
+ }
186
+
187
+ function readZipEntries(zipBuffer) {
188
+ if (!Buffer.isBuffer(zipBuffer) || zipBuffer.length === 0 || zipBuffer.length > MAX_PACKAGE_BYTES) {
189
+ return Promise.reject(new Error("Pet package is empty or exceeds 12 MB"));
190
+ }
191
+ return new Promise((resolve, reject) => {
192
+ yauzl.fromBuffer(zipBuffer, { lazyEntries: true, validateEntrySizes: true }, (openError, zipfile) => {
193
+ if (openError) return reject(new Error(`Invalid pet package: ${openError.message}`));
194
+ const entries = new Map();
195
+ let settled = false;
196
+ const fail = (error) => {
197
+ if (settled) return;
198
+ settled = true;
199
+ try { zipfile.close(); } catch {}
200
+ reject(error);
201
+ };
202
+ zipfile.on("error", (error) => fail(new Error(`Invalid pet package: ${error.message}`)));
203
+ zipfile.on("entry", (entry) => {
204
+ const name = String(entry.fileName || "");
205
+ const unixMode = (entry.externalFileAttributes >>> 16) & 0xffff;
206
+ if ((unixMode & 0xf000) === 0xa000) {
207
+ fail(new Error("Pet package entries must not be symbolic links"));
208
+ return;
209
+ }
210
+ if (name !== PET_MANIFEST && name !== PET_SPRITESHEET) {
211
+ fail(new Error("A standard pet package must contain only pet.json and spritesheet.webp at its root"));
212
+ return;
213
+ }
214
+ if (entries.has(name)) {
215
+ fail(new Error(`Pet package contains duplicate ${name}`));
216
+ return;
217
+ }
218
+ const limit = name === PET_MANIFEST ? MAX_MANIFEST_BYTES : MAX_SPRITESHEET_BYTES;
219
+ if (entry.uncompressedSize <= 0 || entry.uncompressedSize > limit) {
220
+ fail(new Error(`${name} is empty or too large`));
221
+ return;
222
+ }
223
+ zipfile.openReadStream(entry, (streamError, stream) => {
224
+ if (streamError) return fail(new Error(`Could not read ${name}: ${streamError.message}`));
225
+ const chunks = [];
226
+ let total = 0;
227
+ stream.on("data", (chunk) => {
228
+ total += chunk.length;
229
+ if (total > limit) {
230
+ stream.destroy(new Error(`${name} is too large`));
231
+ return;
232
+ }
233
+ chunks.push(chunk);
234
+ });
235
+ stream.on("error", (error) => fail(error));
236
+ stream.on("end", () => {
237
+ if (settled) return;
238
+ entries.set(name, Buffer.concat(chunks));
239
+ zipfile.readEntry();
240
+ });
241
+ });
242
+ });
243
+ zipfile.on("end", () => {
244
+ if (settled) return;
245
+ settled = true;
246
+ if (entries.size !== 2 || !entries.has(PET_MANIFEST) || !entries.has(PET_SPRITESHEET)) {
247
+ reject(new Error("Pet package must contain pet.json and spritesheet.webp"));
248
+ return;
249
+ }
250
+ resolve(entries);
251
+ });
252
+ zipfile.readEntry();
253
+ });
254
+ });
255
+ }
256
+
257
+ function publicPet(manifest, extra = {}) {
258
+ const assetVersion = extra.assetVersion || "";
259
+ return {
260
+ ...manifest,
261
+ custom: true,
262
+ assetUrl: `/api/pets/local/${encodeURIComponent(manifest.id)}/${PET_SPRITESHEET}${assetVersion ? `?v=${encodeURIComponent(assetVersion)}` : ""}`,
263
+ ...extra,
264
+ };
265
+ }
266
+
267
+ function loadPetDirectory(directory, expectedId = null) {
268
+ const stat = fs.lstatSync(directory);
269
+ if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error("Pet path is not a directory");
270
+ const manifestPath = path.join(directory, PET_MANIFEST);
271
+ const spritesheetPath = path.join(directory, PET_SPRITESHEET);
272
+ const manifestStat = fs.lstatSync(manifestPath);
273
+ const spriteStat = fs.lstatSync(spritesheetPath);
274
+ if (!manifestStat.isFile() || manifestStat.isSymbolicLink() || !spriteStat.isFile() || spriteStat.isSymbolicLink()) {
275
+ throw new Error("Pet assets must be regular files");
276
+ }
277
+ if (manifestStat.size <= 0 || manifestStat.size > MAX_MANIFEST_BYTES) {
278
+ throw new Error("pet.json is missing or too large");
279
+ }
280
+ if (spriteStat.size <= 0 || spriteStat.size > MAX_SPRITESHEET_BYTES) {
281
+ throw new Error("spritesheet.webp is missing or too large");
282
+ }
283
+ const cacheKey = [
284
+ manifestStat.mtimeMs,
285
+ manifestStat.size,
286
+ spriteStat.mtimeMs,
287
+ spriteStat.size,
288
+ ].join(":");
289
+ const cacheId = directory;
290
+ const cached = petDirectoryCache.get(cacheId);
291
+ if (cached?.cacheKey === cacheKey) return cached.value;
292
+ const result = validatePackageFiles(fs.readFileSync(manifestPath), fs.readFileSync(spritesheetPath));
293
+ if (expectedId && result.manifest.id !== expectedId) throw new Error("Pet directory and manifest id do not match");
294
+ const value = {
295
+ ...result,
296
+ directory,
297
+ spritesheetPath,
298
+ assetVersion: `${Math.trunc(spriteStat.mtimeMs)}-${spriteStat.size}`,
299
+ };
300
+ petDirectoryCache.set(cacheId, { cacheKey, value });
301
+ return value;
302
+ }
303
+
304
+ /**
305
+ * Move third-party packages out of directories whose id we have since reserved.
306
+ *
307
+ * `bot` became a built-in in 0.93.0. A user who had imported a package with that id
308
+ * would otherwise lose it silently: BUILTIN_IDS skips it in every listing, and
309
+ * removeInstalledPet routes it to hideBuiltinPet, which rejects a non-removable
310
+ * built-in — so the directory became invisible AND undeletable, up to 10 MB of it.
311
+ *
312
+ * Renaming keeps the package usable instead of just deleting it. Idempotent by
313
+ * construction: after the rename the reserved path no longer exists. If the manifest
314
+ * rewrite fails mid-way the package is unusable but freely removable, which still
315
+ * beats the state above.
316
+ */
317
+ function reclaimReservedPetDirectories(root) {
318
+ for (const reserved of BUILTIN_IDS) {
319
+ const source = path.join(root, reserved);
320
+ if (!fs.existsSync(path.join(source, PET_MANIFEST))) continue;
321
+ let target = `${reserved}-imported`;
322
+ for (let suffix = 2; fs.existsSync(path.join(root, target)); suffix += 1) {
323
+ target = `${reserved}-imported-${suffix}`;
324
+ }
325
+ try {
326
+ fs.renameSync(source, path.join(root, target));
327
+ } catch {
328
+ continue;
329
+ }
330
+ // The manifest id must match the directory name or the package fails to load.
331
+ const manifestPath = path.join(root, target, PET_MANIFEST);
332
+ try {
333
+ const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
334
+ manifest.id = target;
335
+ fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
336
+ } catch {
337
+ // Left unusable but removable; nothing else to do here.
338
+ }
339
+ }
340
+ }
341
+
342
+ function listInstalledPets() {
343
+ migrateLegacyCodexPets();
344
+ const root = resolvePetsDir();
345
+ reclaimReservedPetDirectories(root);
346
+ let names = [];
347
+ try { names = fs.readdirSync(root); } catch (error) {
348
+ if (error?.code === "ENOENT") return [];
349
+ throw error;
350
+ }
351
+ const pets = [];
352
+ for (const name of names) {
353
+ if (!PET_ID_RE.test(name) || BUILTIN_IDS.has(name)) continue;
354
+ try {
355
+ const loaded = loadPetDirectory(path.join(root, name), name);
356
+ pets.push(publicPet(loaded.manifest, { assetVersion: loaded.assetVersion }));
357
+ } catch {
358
+ // Invalid or partially copied directories are ignored until they become valid.
359
+ }
360
+ }
361
+ return pets.sort((a, b) => a.displayName.localeCompare(b.displayName));
362
+ }
363
+
364
+ // Atomically writes one validated pet into `root` (staged dir → rename), optionally
365
+ // dropping `markerName` inside the pet directory. Returns the loaded asset info.
366
+ function writePetIntoDir(root, manifest, spritesheetBuffer, markerName = null) {
367
+ fs.mkdirSync(root, { recursive: true, mode: 0o700 });
368
+ const stage = path.join(root, `.tokenusage-pet-${process.pid}-${crypto.randomBytes(6).toString("hex")}`);
369
+ const destination = path.join(root, manifest.id);
370
+ const backup = `${stage}-backup`;
371
+ fs.mkdirSync(stage, { mode: 0o700 });
372
+ try {
373
+ fs.writeFileSync(path.join(stage, PET_MANIFEST), `${JSON.stringify({
374
+ id: manifest.id,
375
+ displayName: manifest.displayName,
376
+ description: manifest.description,
377
+ spritesheetPath: PET_SPRITESHEET,
378
+ ...(manifest.spriteVersionNumber === 2 ? { spriteVersionNumber: 2 } : {}),
379
+ kind: manifest.kind,
380
+ }, null, 2)}\n`, { mode: 0o600 });
381
+ fs.writeFileSync(path.join(stage, PET_SPRITESHEET), spritesheetBuffer, { mode: 0o600 });
382
+ if (markerName) fs.writeFileSync(path.join(stage, markerName), "", { mode: 0o600 });
383
+ loadPetDirectory(stage, manifest.id);
384
+ petDirectoryCache.delete(destination);
385
+ if (fs.existsSync(destination)) fs.renameSync(destination, backup);
386
+ fs.renameSync(stage, destination);
387
+ petDirectoryCache.delete(stage);
388
+ } catch (error) {
389
+ petDirectoryCache.delete(stage);
390
+ fs.rmSync(stage, { recursive: true, force: true });
391
+ if (!fs.existsSync(destination) && fs.existsSync(backup)) fs.renameSync(backup, destination);
392
+ throw error;
393
+ }
394
+ try { fs.rmSync(backup, { recursive: true, force: true }); } catch {}
395
+ return loadPetDirectory(destination, manifest.id);
396
+ }
397
+
398
+ function installValidatedPackage(manifestBuffer, spritesheetBuffer) {
399
+ const { manifest } = validatePackageFiles(manifestBuffer, spritesheetBuffer);
400
+ const installed = writePetIntoDir(resolvePetsDir(), manifest, spritesheetBuffer);
401
+ return publicPet(manifest, { assetVersion: installed.assetVersion });
402
+ }
403
+
404
+ async function importPetZip(zipBuffer) {
405
+ const entries = await readZipEntries(zipBuffer);
406
+ return installValidatedPackage(entries.get(PET_MANIFEST), entries.get(PET_SPRITESHEET));
407
+ }
408
+
409
+ function petIdFromCodexPetsUrl(input) {
410
+ const raw = String(input || "").trim();
411
+ if (PET_ID_RE.test(raw)) return raw;
412
+ let parsed;
413
+ try { parsed = new URL(raw); } catch { throw new Error("Enter a Codex Pets URL or pet id"); }
414
+ if (parsed.protocol !== "https:" || parsed.hostname !== "codex-pets.net") {
415
+ throw new Error("Only https://codex-pets.net pet URLs are supported");
416
+ }
417
+ const hashMatch = parsed.hash.match(/^#\/pets\/([a-z0-9-]+)\/?$/i);
418
+ const pathMatch = parsed.pathname.match(/^\/api\/pets\/([a-z0-9-]+)(?:\/download)?\/?$/i);
419
+ const id = String(hashMatch?.[1] || pathMatch?.[1] || "").toLowerCase();
420
+ if (!PET_ID_RE.test(id)) throw new Error("The Codex Pets URL does not contain a valid pet id");
421
+ return id;
422
+ }
423
+
424
+ async function installFromCodexPets(input, fetchImpl = fetch) {
425
+ const id = petIdFromCodexPetsUrl(input);
426
+ const controller = new AbortController();
427
+ const timeout = setTimeout(() => controller.abort(), 30_000);
428
+ timeout.unref?.();
429
+ try {
430
+ const response = await fetchImpl(`https://codex-pets.net/api/pets/${encodeURIComponent(id)}/download`, {
431
+ redirect: "follow",
432
+ signal: controller.signal,
433
+ headers: { accept: "application/zip", "user-agent": "tokenusage-cli Pet Importer" },
434
+ });
435
+ if (!response.ok) throw new Error(`Codex Pets download failed with HTTP ${response.status}`);
436
+ const length = Number(response.headers.get("content-length") || 0);
437
+ if (length > MAX_PACKAGE_BYTES) throw new Error("Pet package exceeds 12 MB");
438
+ const chunks = [];
439
+ let total = 0;
440
+ for await (const chunk of response.body || []) {
441
+ total += chunk.length;
442
+ if (total > MAX_PACKAGE_BYTES) throw new Error("Pet package exceeds 12 MB");
443
+ chunks.push(Buffer.from(chunk));
444
+ }
445
+ const body = Buffer.concat(chunks);
446
+ return await importPetZip(body);
447
+ } finally {
448
+ clearTimeout(timeout);
449
+ }
450
+ }
451
+
452
+ function removeInstalledPet(id) {
453
+ const normalized = String(id || "").trim().toLowerCase();
454
+ if (!PET_ID_RE.test(normalized)) throw new Error("Invalid pet id");
455
+ if (BUILTIN_IDS.has(normalized)) return hideBuiltinPet(normalized);
456
+ const root = resolvePetsDir();
457
+ const destination = path.join(root, normalized);
458
+ if (!destination.startsWith(`${root}${path.sep}`)) throw new Error("Invalid pet path");
459
+ fs.rmSync(destination, { recursive: true, force: true });
460
+ petDirectoryCache.delete(destination);
461
+ return { id: normalized };
462
+ }
463
+
464
+ function resolvePetAsset(id) {
465
+ // Native hosts can ask for the persisted custom pet before the dashboard has
466
+ // listed the catalog. Migrate first so an upgrade does not turn that first
467
+ // request into a 404 and reset the user's selection.
468
+ migrateLegacyCodexPets();
469
+ const normalized = String(id || "").trim().toLowerCase();
470
+ if (!PET_ID_RE.test(normalized) || BUILTIN_IDS.has(normalized)) return null;
471
+ try { return loadPetDirectory(path.join(resolvePetsDir(), normalized), normalized); } catch { return null; }
472
+ }
473
+
474
+ // --- One-time migration: copy legacy pets out of the shared Codex dir into our own ---
475
+
476
+ function migrateLegacyCodexPets() {
477
+ const root = resolvePetsDir();
478
+ const marker = path.join(root, MIGRATION_MARKER);
479
+ try { if (fs.existsSync(marker)) return { migrated: 0 }; } catch { return { migrated: 0 }; }
480
+ try { fs.mkdirSync(root, { recursive: true, mode: 0o700 }); } catch { return { migrated: 0 }; }
481
+ let migrated = 0;
482
+ let names = [];
483
+ let scanComplete = false;
484
+ try {
485
+ names = fs.readdirSync(resolveCodexPetsDir());
486
+ scanComplete = true;
487
+ } catch (error) {
488
+ // A missing legacy directory is a completed no-op. Permission and I/O
489
+ // failures are not: leave the marker absent so the next launch can retry.
490
+ if (error?.code === "ENOENT") scanComplete = true;
491
+ }
492
+ let copyFailed = false;
493
+ for (const name of names) {
494
+ if (!PET_ID_RE.test(name) || BUILTIN_IDS.has(name)) continue;
495
+ if (fs.existsSync(path.join(root, name))) continue; // never clobber an existing local pet
496
+ let loaded;
497
+ try {
498
+ loaded = loadPetDirectory(path.join(resolveCodexPetsDir(), name), name);
499
+ } catch {
500
+ // Invalid legacy packages are ignored just as they were by the old catalog.
501
+ continue;
502
+ }
503
+ try {
504
+ writePetIntoDir(root, loaded.manifest, fs.readFileSync(loaded.spritesheetPath));
505
+ migrated += 1;
506
+ } catch {
507
+ copyFailed = true;
508
+ }
509
+ }
510
+ if (scanComplete && !copyFailed) {
511
+ try { fs.writeFileSync(marker, `${new Date().toISOString()}\n`, { mode: 0o600 }); } catch {}
512
+ }
513
+ return { migrated };
514
+ }
515
+
516
+ // --- Reverse import: pull Codex's own pets into Token Usage ---
517
+
518
+ // Resolved per call (not frozen at load) so an env override applies at runtime.
519
+ function resolveCodexAsarPath() {
520
+ return process.env.TOKENUSAGE_CODEX_ASAR
521
+ || "/Applications/Codex.app/Contents/Resources/app.asar";
522
+ }
523
+ // Codex ships these native companions bundled inside its app; the display names are
524
+ // stable brand labels. Anything not listed falls back to a capitalized id.
525
+ const CODEX_BUILTIN_NAMES = {
526
+ rocky: "Rocky", seedy: "Seedy", hoots: "Hoots", dewey: "Dewey", fireball: "Fireball",
527
+ stacky: "Stacky", codex: "Codex", bsod: "BSOD", "null-signal": "Null Signal",
528
+ };
529
+
530
+ // Parses the asar header (Chromium Pickle) and returns the file tree plus the byte
531
+ // offset where file contents begin. Pure Node, no dependency — asar's layout is stable.
532
+ function readAsarHeader(fd) {
533
+ const head = Buffer.alloc(16);
534
+ if (fs.readSync(fd, head, 0, 16, 0) < 16) throw new Error("asar too small");
535
+ const headerPayloadSize = head.readUInt32LE(4);
536
+ const jsonStrLen = head.readUInt32LE(12);
537
+ if (jsonStrLen <= 0 || jsonStrLen > 64 * 1024 * 1024) throw new Error("asar header size out of range");
538
+ const jsonBuf = Buffer.alloc(jsonStrLen);
539
+ fs.readSync(fd, jsonBuf, 0, jsonStrLen, 16);
540
+ const header = JSON.parse(jsonBuf.toString("utf8"));
541
+ const base = 8 + headerPayloadSize;
542
+ return { header, baseOffset: base % 4 ? base + 4 - (base % 4) : base };
543
+ }
544
+
545
+ // Reads Codex's bundled companion spritesheets out of the app's asar. Returns
546
+ // [{ id, displayName, description, spriteVersionNumber, buffer }]. Degrades to [] if
547
+ // Codex isn't installed or the bundle can't be read.
548
+ function readCodexBuiltinPets(asarPath = resolveCodexAsarPath()) {
549
+ const resolvedAsarPath = path.resolve(asarPath);
550
+ let asarStat;
551
+ try { asarStat = fs.statSync(resolvedAsarPath); } catch { return []; }
552
+ const cacheKey = `${resolvedAsarPath}:${asarStat.mtimeMs}:${asarStat.size}`;
553
+ if (codexAsarCache?.key === cacheKey) return codexAsarCache.pets;
554
+
555
+ let fd;
556
+ try { fd = fs.openSync(resolvedAsarPath, "r"); } catch { return []; }
557
+ try {
558
+ const { header, baseOffset } = readAsarHeader(fd);
559
+ const entries = [];
560
+ (function walk(node) {
561
+ for (const [name, value] of Object.entries(node?.files || {})) {
562
+ if (value?.files) walk(value);
563
+ else if (/-spritesheet-.*\.webp$/i.test(name) && value?.offset != null) entries.push([name, value]);
564
+ }
565
+ })(header);
566
+ const byId = new Map();
567
+ for (const [name, entry] of entries) {
568
+ const id = name.replace(/-spritesheet-.*$/i, "").toLowerCase();
569
+ if (!PET_ID_RE.test(id) || BUILTIN_IDS.has(id) || byId.has(id)) continue;
570
+ const size = Number(entry.size);
571
+ if (!(size > 0) || size > MAX_SPRITESHEET_BYTES) continue;
572
+ const buffer = Buffer.alloc(size);
573
+ fs.readSync(fd, buffer, 0, size, baseOffset + Number(entry.offset));
574
+ let dimensions;
575
+ try { dimensions = readWebpDimensions(buffer); } catch { continue; }
576
+ const spriteVersionNumber = dimensions.width === 1536 && dimensions.height === 2288 ? 2
577
+ : dimensions.width === 1536 && dimensions.height === 1872 ? 1 : 0;
578
+ if (!spriteVersionNumber) continue;
579
+ byId.set(id, {
580
+ id,
581
+ displayName: CODEX_BUILTIN_NAMES[id] || (id.charAt(0).toUpperCase() + id.slice(1)),
582
+ description: "Built-in Codex companion.",
583
+ spriteVersionNumber,
584
+ buffer,
585
+ });
586
+ }
587
+ const pets = [...byId.values()];
588
+ codexAsarCache = { key: cacheKey, pets };
589
+ return pets;
590
+ } catch {
591
+ codexAsarCache = { key: cacheKey, pets: [] };
592
+ return [];
593
+ }
594
+ finally { try { fs.closeSync(fd); } catch {} }
595
+ }
596
+
597
+ // Preview URL for an importable Codex pet (served before it lands in our own dir).
598
+ function codexAssetUrl(id, version) {
599
+ return `/api/pets/codex/${encodeURIComponent(id)}/${PET_SPRITESHEET}${version ? `?v=${encodeURIComponent(version)}` : ""}`;
600
+ }
601
+
602
+ // Lists Codex pets that could be imported but aren't in Token Usage yet: valid
603
+ // packages in ~/.codex/pets plus Codex's app-bundled companions. Each carries an
604
+ // assetUrl so the picker can preview sprites.
605
+ function listCodexImportablePets() {
606
+ const alreadyHere = new Set(listInstalledPets().map((pet) => pet.id));
607
+ const result = new Map();
608
+ const codexRoot = resolveCodexPetsDir();
609
+ let names = [];
610
+ try { names = fs.readdirSync(codexRoot); } catch { names = []; }
611
+ for (const name of names) {
612
+ if (!PET_ID_RE.test(name) || BUILTIN_IDS.has(name) || alreadyHere.has(name)) continue;
613
+ try {
614
+ const loaded = loadPetDirectory(path.join(codexRoot, name), name);
615
+ result.set(name, {
616
+ ...loaded.manifest,
617
+ custom: true,
618
+ assetUrl: codexAssetUrl(name, loaded.assetVersion),
619
+ assetVersion: loaded.assetVersion,
620
+ source: "codex-dir",
621
+ });
622
+ } catch {}
623
+ }
624
+ for (const pet of readCodexBuiltinPets()) {
625
+ if (alreadyHere.has(pet.id) || result.has(pet.id)) continue;
626
+ result.set(pet.id, {
627
+ id: pet.id,
628
+ displayName: pet.displayName,
629
+ description: pet.description,
630
+ spritesheetPath: PET_SPRITESHEET,
631
+ spriteVersionNumber: pet.spriteVersionNumber,
632
+ custom: true,
633
+ assetUrl: codexAssetUrl(pet.id, `app${pet.spriteVersionNumber}`),
634
+ source: "codex-app",
635
+ });
636
+ }
637
+ return [...result.values()].sort((a, b) => a.displayName.localeCompare(b.displayName));
638
+ }
639
+
640
+ // Returns { buffer, contentLength } for an importable Codex pet's spritesheet — from
641
+ // ~/.codex/pets first, then the app bundle. Powers the picker preview route.
642
+ function readCodexImportableAsset(id) {
643
+ const normalized = String(id || "").trim().toLowerCase();
644
+ if (!PET_ID_RE.test(normalized) || BUILTIN_IDS.has(normalized)) return null;
645
+ const codexDir = path.join(resolveCodexPetsDir(), normalized);
646
+ try {
647
+ const loaded = loadPetDirectory(codexDir, normalized);
648
+ return { buffer: fs.readFileSync(loaded.spritesheetPath) };
649
+ } catch {}
650
+ for (const pet of readCodexBuiltinPets()) {
651
+ if (pet.id === normalized) return { buffer: pet.buffer };
652
+ }
653
+ return null;
654
+ }
655
+
656
+ function importFromCodex(ids) {
657
+ const requested = new Set(
658
+ (Array.isArray(ids) ? ids : [])
659
+ .map((id) => String(id || "").trim().toLowerCase())
660
+ .filter((id) => PET_ID_RE.test(id) && !BUILTIN_IDS.has(id)),
661
+ );
662
+ if (requested.size === 0) throw new Error("No valid Codex pet ids to import");
663
+ const root = resolvePetsDir();
664
+ // The listing excludes already-installed ids, but enforce the same rule at
665
+ // the write boundary so a handcrafted local API request cannot overwrite a
666
+ // Token Usage-owned pet with Codex's copy.
667
+ for (const id of [...requested]) {
668
+ if (fs.existsSync(path.join(root, id))) requested.delete(id);
669
+ }
670
+ if (requested.size === 0) throw new Error("Requested Codex pets are already installed");
671
+ const codexRoot = resolveCodexPetsDir();
672
+ const imported = [];
673
+ for (const id of [...requested]) {
674
+ try {
675
+ const loaded = loadPetDirectory(path.join(codexRoot, id), id);
676
+ const installed = writePetIntoDir(root, loaded.manifest, fs.readFileSync(loaded.spritesheetPath));
677
+ imported.push(publicPet(loaded.manifest, { assetVersion: installed.assetVersion }));
678
+ requested.delete(id);
679
+ } catch {}
680
+ }
681
+ if (requested.size > 0) {
682
+ for (const pet of readCodexBuiltinPets()) {
683
+ if (!requested.has(pet.id)) continue;
684
+ const manifest = normalizeManifest({
685
+ id: pet.id,
686
+ displayName: pet.displayName,
687
+ description: pet.description,
688
+ spritesheetPath: PET_SPRITESHEET,
689
+ ...(pet.spriteVersionNumber === 2 ? { spriteVersionNumber: 2 } : {}),
690
+ });
691
+ try {
692
+ const installed = writePetIntoDir(root, manifest, pet.buffer);
693
+ imported.push(publicPet(manifest, { assetVersion: installed.assetVersion }));
694
+ requested.delete(pet.id);
695
+ } catch {}
696
+ }
697
+ }
698
+ if (imported.length === 0) throw new Error("None of the requested Codex pets could be imported");
699
+ return { imported };
700
+ }
701
+
702
+ module.exports = {
703
+ MAX_PACKAGE_BYTES,
704
+ importFromCodex,
705
+ importPetZip,
706
+ installFromCodexPets,
707
+ listCodexImportablePets,
708
+ listInstalledPets,
709
+ migrateLegacyCodexPets,
710
+ normalizeManifest,
711
+ petIdFromCodexPetsUrl,
712
+ readCodexBuiltinPets,
713
+ readCodexImportableAsset,
714
+ readHiddenBuiltinIds,
715
+ readWebpDimensions,
716
+ reclaimReservedPetDirectories,
717
+ removeInstalledPet,
718
+ resolveCodexPetsDir,
719
+ resolvePetAsset,
720
+ resolvePetsDir,
721
+ validatePackageFiles,
722
+ };