Codex
1717 lines
74 KiB
TypeScript
1717 lines
74 KiB
TypeScript
import { closeSync, copyFileSync, createReadStream, existsSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, readlinkSync, readSync, realpathSync, statSync, writeFileSync } from "node:fs";
|
|
import { homedir } from "node:os";
|
|
import path from "node:path";
|
|
import { createInterface } from "node:readline";
|
|
import { spawnSync } from "node:child_process";
|
|
import { repoRoot } from "./config";
|
|
import type { RenderedCliResult } from "./output";
|
|
|
|
type CodexTraceAction = "help" | "list" | "collect" | "show" | "grep" | "active";
|
|
type CodexTraceKind = "session-jsonl" | "history-jsonl" | "shell-snapshot" | "log" | "trace-named" | "jsonl" | "sqlite-db" | "sqlite-sidecar" | "unrecognized";
|
|
type CodexTraceOutput = "text" | "wide" | "name" | "json" | "yaml";
|
|
|
|
interface CodexTraceOptions {
|
|
action: CodexTraceAction;
|
|
root: string;
|
|
outputDir: string | null;
|
|
file: string | null;
|
|
session: string | null;
|
|
limit: number;
|
|
maxDepth: number;
|
|
maxFileBytes: number;
|
|
tailBytes: number;
|
|
includeSqlite: boolean;
|
|
includeSensitive: boolean;
|
|
includeCache: boolean;
|
|
dryRun: boolean;
|
|
full: boolean;
|
|
allowOutsideRoot: boolean;
|
|
pattern: string | null;
|
|
fixed: boolean;
|
|
deep: boolean;
|
|
allFiles: boolean;
|
|
messagesOnly: boolean;
|
|
toolsOnly: boolean;
|
|
failedOnly: boolean;
|
|
includeOutput: boolean;
|
|
tool: string | null;
|
|
includeSystem: boolean;
|
|
contextChars: number;
|
|
since: string | null;
|
|
fileLimit: number;
|
|
output: CodexTraceOutput;
|
|
}
|
|
|
|
interface CodexTraceCandidate {
|
|
path: string;
|
|
relativePath: string;
|
|
kind: CodexTraceKind;
|
|
bytes: number;
|
|
mtimeMs: number;
|
|
included: boolean;
|
|
skippedReason: string | null;
|
|
}
|
|
|
|
interface ToolCallInfo {
|
|
name: string | null;
|
|
input: string | null;
|
|
line: number;
|
|
timestamp: string | null;
|
|
}
|
|
|
|
const defaultLimit = 30;
|
|
const maxLimit = 500;
|
|
const defaultMaxDepth = 8;
|
|
const maxDepthLimit = 16;
|
|
const defaultMaxFileBytes = 25 * 1024 * 1024;
|
|
const maxFileBytesLimit = 512 * 1024 * 1024;
|
|
const defaultTailBytes = 12_000;
|
|
const maxTailBytes = 1_000_000;
|
|
const defaultContextChars = 700;
|
|
const maxContextChars = 4_000;
|
|
const defaultFileLimit = 8;
|
|
const maxFileLimit = 50;
|
|
|
|
export function codexTraceHelp(): Record<string, unknown> {
|
|
return {
|
|
ok: true,
|
|
command: "codex trace",
|
|
output: "text",
|
|
description: "Collect bounded local Codex trace artifacts. Defaults to ~/.codex and can scan another root with --root <dir>.",
|
|
usage: [
|
|
"bun scripts/cli.ts codex trace list [--root ~/.codex] [--limit 30]",
|
|
"bun scripts/cli.ts codex trace active [--root ~/.codex]",
|
|
"bun scripts/cli.ts codex trace grep --session <id> --pattern 'playwright|auth-login-failed' [--since ISO]",
|
|
"bun scripts/cli.ts codex trace grep --session <id> --messages --pattern 'Playwright|web-probe'",
|
|
"bun scripts/cli.ts codex trace grep --session <id> --failed-only [--tool exec_command]",
|
|
"bun scripts/cli.ts codex trace grep --pattern 'playwright|auth-login-failed' [--file sessions/...jsonl] [--since ISO]",
|
|
"bun scripts/cli.ts codex trace collect [--root ~/.codex] [--output .state/codex-trace/<timestamp>] [--limit 30]",
|
|
"bun scripts/cli.ts codex trace show --session <id> [--root ~/.codex] [--tail-bytes 12000]",
|
|
],
|
|
safety: [
|
|
"Default scan includes sessions/*.jsonl, history.jsonl, shell_snapshots, *.log, and trace-named text files.",
|
|
"auth.json, config.toml, cache/.tmp/generated_images, and sqlite files are skipped by default.",
|
|
"grep parses JSONL records, skips bootstrap/system payloads by default, and returns bounded match-centered summaries instead of whole lines.",
|
|
"Use --include-sqlite or --include-sensitive only for reviewed local diagnostics; values are not printed unless show reads a text file.",
|
|
"collect copies bounded files and writes a manifest; it does not compress, upload, or delete source files.",
|
|
],
|
|
options: {
|
|
"--root <dir>": "Codex home or another trace root. Defaults to ~/.codex.",
|
|
"--output <dir>": "Collect destination. Defaults to .state/codex-trace/<timestamp>.",
|
|
"--limit <n>": `Maximum included files, default ${defaultLimit}, max ${maxLimit}.`,
|
|
"--max-depth <n>": `Recursive scan depth, default ${defaultMaxDepth}, max ${maxDepthLimit}.`,
|
|
"--max-file-bytes <n|25MiB>": "Skip files larger than this during collect/list inclusion.",
|
|
"--include-sqlite": "Include *.sqlite and sqlite sidecars if under max size.",
|
|
"--include-sensitive": "Allow auth/config-looking files. Off by default.",
|
|
"--include-cache": "Traverse cache, .tmp, generated_images, plugins, and skills directories. Off by default.",
|
|
"--dry-run": "For collect, report the plan without copying files.",
|
|
"--file <path>": "For show, file path relative to --root or an absolute path under --root.",
|
|
"--session <id>": "For show/grep, resolve a Codex session by full or short session id instead of copying the JSONL path.",
|
|
"--pattern <regex>": "For grep, pattern to match against structured event text.",
|
|
"--fixed": "For grep, treat --pattern as a literal string.",
|
|
"--deep": "For grep, parse every JSONL line. Default uses a raw-line prefilter for speed.",
|
|
"--all-files": "For grep without --file/--session, scan all included trace files instead of active/recent sessions only.",
|
|
"--messages": "For grep, only return user/assistant message events.",
|
|
"--tools": "For grep, only return tool calls/outputs.",
|
|
"--failed-only": "For grep, only return failed tool outputs with folded error summaries.",
|
|
"--tool <name|regex>": "For grep, restrict tool calls/outputs by tool name such as exec_command or imagegen.",
|
|
"--include-output": "For grep, allow matched tool output snippets. Default folds tool output and shows input/error summary.",
|
|
"--since <ISO>": "For grep, skip JSONL events before the timestamp string.",
|
|
"--context-chars <n>": `For grep, max summary characters per match, default ${defaultContextChars}, max ${maxContextChars}.`,
|
|
"--file-limit <n>": `For grep without --file, max target files, default ${defaultFileLimit}, max ${maxFileLimit}.`,
|
|
"--include-system": "For grep, include session_meta/system instruction records. Off by default.",
|
|
"-o json|yaml|name|wide": "Output mode. Default is concise text/table.",
|
|
"--tail-bytes <n>": `For show, tail bytes to return, default ${defaultTailBytes}, max ${maxTailBytes}.`,
|
|
"--full": "For show, read from the beginning up to --max-file-bytes instead of tailing.",
|
|
},
|
|
};
|
|
}
|
|
|
|
export async function runCodexTraceCommand(args: string[]): Promise<Record<string, unknown> | RenderedCliResult> {
|
|
const options = parseCodexTraceOptions(args);
|
|
if (options.action === "help") return renderCodexTraceResult(options, "codex trace help", codexTraceHelp());
|
|
if (options.action === "active") return codexTraceActive(options);
|
|
if (options.action === "show") return codexTraceShow(options);
|
|
if (options.action === "grep") return codexTraceGrep(options);
|
|
const candidates = scanCodexTraceRoot(options);
|
|
if (options.action === "list") return codexTraceList(options, candidates);
|
|
return codexTraceCollect(options, candidates);
|
|
}
|
|
|
|
function parseCodexTraceOptions(args: string[]): CodexTraceOptions {
|
|
const rawAction = args[0];
|
|
const action: CodexTraceAction =
|
|
rawAction === undefined || rawAction === "help" || rawAction === "--help" || rawAction === "-h" ? "help"
|
|
: rawAction === "list" || rawAction === "collect" || rawAction === "show" || rawAction === "grep" || rawAction === "active" ? rawAction
|
|
: (() => { throw new Error(`codex trace action must be one of: list, active, grep, collect, show, help; got ${rawAction}`); })();
|
|
const optionArgs = action === "help" && rawAction === undefined ? args : args.slice(1);
|
|
assertKnownOptions(optionArgs, {
|
|
flags: ["--dry-run", "--full", "--include-sqlite", "--include-sensitive", "--include-cache", "--allow-outside-root", "--include-system", "--fixed", "--deep", "--all-files", "--messages", "--tools", "--failed-only", "--include-output", "--wide", "--help", "-h"],
|
|
values: ["--root", "--output", "--file", "--session", "--limit", "--max-depth", "--max-file-bytes", "--tail-bytes", "--pattern", "--tool", "--since", "--context-chars", "--file-limit", "-o", "--format"],
|
|
});
|
|
if (optionArgs.includes("--help") || optionArgs.includes("-h")) {
|
|
return {
|
|
action: "help",
|
|
root: defaultCodexRoot(),
|
|
outputDir: null,
|
|
file: null,
|
|
session: null,
|
|
limit: defaultLimit,
|
|
maxDepth: defaultMaxDepth,
|
|
maxFileBytes: defaultMaxFileBytes,
|
|
tailBytes: defaultTailBytes,
|
|
includeSqlite: false,
|
|
includeSensitive: false,
|
|
includeCache: false,
|
|
dryRun: false,
|
|
full: false,
|
|
allowOutsideRoot: false,
|
|
pattern: null,
|
|
fixed: false,
|
|
deep: false,
|
|
allFiles: false,
|
|
messagesOnly: false,
|
|
toolsOnly: false,
|
|
failedOnly: false,
|
|
includeOutput: false,
|
|
tool: null,
|
|
includeSystem: false,
|
|
contextChars: defaultContextChars,
|
|
since: null,
|
|
fileLimit: defaultFileLimit,
|
|
output: "text",
|
|
};
|
|
}
|
|
const root = resolveUserPath(optionValue(optionArgs, "--root") ?? defaultCodexRoot());
|
|
const positionalPattern = action === "grep" && optionArgs[0] !== undefined && !optionArgs[0].startsWith("-") ? optionArgs[0] : null;
|
|
const output = parseOutputMode(optionValue(optionArgs, "-o") ?? optionValue(optionArgs, "--format"), hasFlag(optionArgs, "--wide"));
|
|
const file = optionValue(optionArgs, "--file") ?? null;
|
|
const session = optionValue(optionArgs, "--session") ?? null;
|
|
if (file !== null && session !== null) throw new Error("codex trace accepts either --file or --session, not both");
|
|
const messagesOnly = hasFlag(optionArgs, "--messages");
|
|
const toolsOnly = hasFlag(optionArgs, "--tools") || hasFlag(optionArgs, "--failed-only") || optionValue(optionArgs, "--tool") !== undefined;
|
|
if (messagesOnly && toolsOnly) throw new Error("codex trace grep accepts either --messages or tool filters, not both");
|
|
return {
|
|
action,
|
|
root,
|
|
outputDir: optionValue(optionArgs, "--output") === undefined ? null : resolveUserPath(optionValue(optionArgs, "--output") ?? ""),
|
|
file,
|
|
session,
|
|
limit: positiveIntegerOption(optionArgs, "--limit", defaultLimit, maxLimit),
|
|
maxDepth: positiveIntegerOption(optionArgs, "--max-depth", defaultMaxDepth, maxDepthLimit),
|
|
maxFileBytes: bytesOption(optionArgs, "--max-file-bytes", defaultMaxFileBytes, maxFileBytesLimit),
|
|
tailBytes: positiveIntegerOption(optionArgs, "--tail-bytes", defaultTailBytes, maxTailBytes),
|
|
includeSqlite: hasFlag(optionArgs, "--include-sqlite"),
|
|
includeSensitive: hasFlag(optionArgs, "--include-sensitive"),
|
|
includeCache: hasFlag(optionArgs, "--include-cache"),
|
|
dryRun: hasFlag(optionArgs, "--dry-run"),
|
|
full: hasFlag(optionArgs, "--full"),
|
|
allowOutsideRoot: hasFlag(optionArgs, "--allow-outside-root"),
|
|
pattern: optionValue(optionArgs, "--pattern") ?? positionalPattern,
|
|
fixed: hasFlag(optionArgs, "--fixed"),
|
|
deep: hasFlag(optionArgs, "--deep"),
|
|
allFiles: hasFlag(optionArgs, "--all-files"),
|
|
messagesOnly,
|
|
toolsOnly,
|
|
failedOnly: hasFlag(optionArgs, "--failed-only"),
|
|
includeOutput: hasFlag(optionArgs, "--include-output") || output === "wide",
|
|
tool: optionValue(optionArgs, "--tool") ?? null,
|
|
includeSystem: hasFlag(optionArgs, "--include-system"),
|
|
contextChars: positiveIntegerOption(optionArgs, "--context-chars", defaultContextChars, maxContextChars),
|
|
since: optionValue(optionArgs, "--since") ?? null,
|
|
fileLimit: positiveIntegerOption(optionArgs, "--file-limit", defaultFileLimit, maxFileLimit),
|
|
output,
|
|
};
|
|
}
|
|
|
|
function codexTraceList(options: CodexTraceOptions, candidates: CodexTraceCandidate[]): Record<string, unknown> | RenderedCliResult {
|
|
const selected = selectedCandidates(options, candidates);
|
|
const raw = {
|
|
ok: true,
|
|
command: "codex trace list",
|
|
root: options.root,
|
|
rootPresent: existsSync(options.root),
|
|
policy: policySummary(options),
|
|
summary: candidateSummary(candidates, selected),
|
|
files: selected.map(candidateRow),
|
|
omitted: Math.max(0, candidates.filter((item) => item.included).length - selected.length),
|
|
skipped: skippedSummary(candidates),
|
|
commands: {
|
|
collect: `bun scripts/cli.ts codex trace collect --root ${shellWord(options.root)} --limit ${options.limit}`,
|
|
show: "bun scripts/cli.ts codex trace show --file <relative-path>",
|
|
},
|
|
valuesPrinted: false,
|
|
};
|
|
return renderCodexTraceResult(options, "codex trace list", raw);
|
|
}
|
|
|
|
function codexTraceCollect(options: CodexTraceOptions, candidates: CodexTraceCandidate[]): Record<string, unknown> | RenderedCliResult {
|
|
const selected = selectedCandidates(options, candidates);
|
|
const outputDir = options.outputDir ?? path.join(repoRoot, ".state", "codex-trace", timestampForPath());
|
|
const copied: Record<string, unknown>[] = [];
|
|
if (!options.dryRun) mkdirSync(outputDir, { recursive: true, mode: 0o700 });
|
|
for (const candidate of selected) {
|
|
const target = path.join(outputDir, candidate.relativePath);
|
|
if (!options.dryRun) {
|
|
mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
|
|
copyFileSync(candidate.path, target);
|
|
}
|
|
copied.push({
|
|
source: candidate.relativePath,
|
|
target: path.relative(outputDir, target),
|
|
kind: candidate.kind,
|
|
bytes: candidate.bytes,
|
|
mtime: new Date(candidate.mtimeMs).toISOString(),
|
|
});
|
|
}
|
|
const manifest = {
|
|
generatedAt: new Date().toISOString(),
|
|
command: "codex trace collect",
|
|
root: options.root,
|
|
outputDir,
|
|
dryRun: options.dryRun,
|
|
policy: policySummary(options),
|
|
summary: candidateSummary(candidates, selected),
|
|
files: copied,
|
|
skipped: skippedSummary(candidates),
|
|
valuesPrinted: false,
|
|
};
|
|
if (!options.dryRun) writeFileSync(path.join(outputDir, "manifest.json"), JSON.stringify(manifest, null, 2) + "\n", { mode: 0o600 });
|
|
const raw = {
|
|
ok: true,
|
|
command: "codex trace collect",
|
|
root: options.root,
|
|
outputDir,
|
|
dryRun: options.dryRun,
|
|
copiedCount: copied.length,
|
|
copiedBytes: selected.reduce((sum, item) => sum + item.bytes, 0),
|
|
manifest: options.dryRun ? null : path.join(outputDir, "manifest.json"),
|
|
policy: policySummary(options),
|
|
files: copied.slice(0, Math.min(copied.length, options.limit)),
|
|
skipped: skippedSummary(candidates),
|
|
valuesPrinted: false,
|
|
};
|
|
return renderCodexTraceResult(options, "codex trace collect", raw);
|
|
}
|
|
|
|
function codexTraceShow(options: CodexTraceOptions): Record<string, unknown> | RenderedCliResult {
|
|
const rootReal = safeRealpath(options.root);
|
|
if (rootReal === null) throw new Error(`codex trace root does not exist: ${options.root}`);
|
|
if (options.file === null && options.session === null) throw new Error("codex trace show requires --file <path> or --session <id>");
|
|
const target = options.session === null
|
|
? candidateFromFile(rootReal, options.root, options.file ?? "")
|
|
: resolveSessionCandidate(rootReal, options.root, options.session);
|
|
const fileReal = safeRealpath(target.path);
|
|
if (fileReal === null) throw new Error(`codex trace file does not exist: ${target.path}`);
|
|
if (!options.allowOutsideRoot && !isWithin(rootReal, fileReal)) {
|
|
throw new Error(`codex trace show refuses file outside --root; pass --root accordingly or --allow-outside-root for reviewed local diagnostics`);
|
|
}
|
|
const stats = statSync(fileReal);
|
|
const relativePath = path.relative(rootReal, fileReal);
|
|
const basename = path.basename(fileReal);
|
|
const kind = classifyTraceKind(relativePath, basename);
|
|
if (!options.includeSensitive && isSensitivePath(normalizePath(relativePath), basename)) {
|
|
throw new Error("codex trace show refuses sensitive-looking files by default; pass --include-sensitive for reviewed local diagnostics");
|
|
}
|
|
const textReadable = isTextReadableTrace(kind, fileReal);
|
|
const readBytes = options.full ? Math.min(stats.size, options.maxFileBytes) : Math.min(stats.size, options.tailBytes);
|
|
const start = options.full ? 0 : Math.max(0, stats.size - readBytes);
|
|
const content = textReadable ? redactTraceText(readFileSlice(fileReal, start, readBytes)) : null;
|
|
const raw = {
|
|
ok: true,
|
|
command: "codex trace show",
|
|
root: options.root,
|
|
file: fileReal,
|
|
relativePath,
|
|
sessionId: extractSessionId(relativePath),
|
|
kind,
|
|
bytes: stats.size,
|
|
mtime: stats.mtime.toISOString(),
|
|
contentPolicy: {
|
|
textReadable,
|
|
mode: options.full ? "head" : "tail",
|
|
start,
|
|
bytesReturned: content === null ? 0 : Buffer.byteLength(content),
|
|
redacted: true,
|
|
fullRequested: options.full,
|
|
truncated: options.full ? stats.size > options.maxFileBytes : stats.size > options.tailBytes,
|
|
},
|
|
content,
|
|
valuesPrinted: content !== null,
|
|
};
|
|
return renderCodexTraceResult(options, "codex trace show", raw);
|
|
}
|
|
|
|
function codexTraceActive(options: CodexTraceOptions): Record<string, unknown> | RenderedCliResult {
|
|
const rootReal = safeRealpath(options.root);
|
|
const procDir = "/proc";
|
|
if (rootReal === null) {
|
|
const raw = {
|
|
ok: true,
|
|
command: "codex trace active",
|
|
root: options.root,
|
|
rootPresent: false,
|
|
supported: existsSync(procDir),
|
|
sessions: [],
|
|
valuesPrinted: false,
|
|
};
|
|
return renderCodexTraceResult(options, "codex trace active", raw);
|
|
}
|
|
const sessions = activeCodexSessionFiles(rootReal).slice(0, options.limit);
|
|
const raw = {
|
|
ok: true,
|
|
command: "codex trace active",
|
|
root: options.root,
|
|
rootPresent: true,
|
|
supported: existsSync(procDir),
|
|
count: sessions.length,
|
|
sessions,
|
|
next: {
|
|
grep: "bun scripts/cli.ts codex trace grep --session <session-id> --pattern <regex>",
|
|
collect: "bun scripts/cli.ts codex trace collect --limit 30",
|
|
},
|
|
valuesPrinted: false,
|
|
};
|
|
return renderCodexTraceResult(options, "codex trace active", raw);
|
|
}
|
|
|
|
async function codexTraceGrep(options: CodexTraceOptions): Promise<Record<string, unknown> | RenderedCliResult> {
|
|
if ((options.pattern === null || options.pattern.length === 0) && !options.failedOnly) {
|
|
throw new Error("codex trace grep requires --pattern <regex>, a positional pattern, or --failed-only");
|
|
}
|
|
const matcher = options.pattern === null || options.pattern.length === 0 ? null : makeMatcher(options.pattern, options.fixed);
|
|
const rootReal = safeRealpath(options.root);
|
|
if (rootReal === null) throw new Error(`codex trace root does not exist: ${options.root}`);
|
|
const files = grepTargetFiles(options, rootReal);
|
|
const results: Record<string, unknown>[] = [];
|
|
let linesScanned = 0;
|
|
let matchedTotal = 0;
|
|
for (const file of files) {
|
|
const report = await grepJsonlFile(file, rootReal, matcher, options, results, options.limit);
|
|
linesScanned += report.linesScanned;
|
|
matchedTotal += report.matchedTotal;
|
|
if (results.length >= options.limit) break;
|
|
}
|
|
const raw = {
|
|
ok: true,
|
|
command: "codex trace grep",
|
|
root: options.root,
|
|
pattern: options.pattern,
|
|
fixed: options.fixed,
|
|
since: options.since,
|
|
policy: {
|
|
limit: options.limit,
|
|
fileLimit: options.fileLimit,
|
|
contextChars: options.contextChars,
|
|
includeSystem: options.includeSystem,
|
|
messagesOnly: options.messagesOnly,
|
|
toolsOnly: options.toolsOnly,
|
|
failedOnly: options.failedOnly,
|
|
includeOutput: options.includeOutput,
|
|
tool: options.tool,
|
|
valuesRedacted: true,
|
|
},
|
|
filesScanned: files.length,
|
|
linesScanned,
|
|
matchedTotal,
|
|
matchesReturned: results.length,
|
|
truncated: matchedTotal > results.length,
|
|
files: files.map((file) => file.relativePath),
|
|
results,
|
|
valuesPrinted: results.length > 0,
|
|
};
|
|
return renderCodexTraceResult(options, "codex trace grep", raw);
|
|
}
|
|
|
|
function renderCodexTraceResult(options: CodexTraceOptions, command: string, raw: Record<string, unknown>): Record<string, unknown> | RenderedCliResult {
|
|
const ok = raw.ok !== false;
|
|
if (options.output === "json") return renderedCliResult(ok, command, `${JSON.stringify(raw, null, 2)}\n`, "application/json");
|
|
if (options.output === "yaml") return renderedCliResult(ok, command, `${Bun.YAML.stringify(raw)}\n`, "application/yaml");
|
|
if (options.output === "name") return renderedCliResult(ok, command, renderCodexTraceNames(raw));
|
|
if (command === "codex trace help" || raw.command === "codex trace") return renderedCliResult(ok, command, renderCodexTraceHelp(raw));
|
|
if (raw.command === "codex trace active") return renderedCliResult(ok, command, renderCodexTraceActive(raw, options));
|
|
if (raw.command === "codex trace grep") return renderedCliResult(ok, command, renderCodexTraceGrep(raw, options));
|
|
if (raw.command === "codex trace list") return renderedCliResult(ok, command, renderCodexTraceList(raw, options));
|
|
if (raw.command === "codex trace collect") return renderedCliResult(ok, command, renderCodexTraceCollect(raw, options));
|
|
if (raw.command === "codex trace show") return renderedCliResult(ok, command, renderCodexTraceShow(raw));
|
|
return raw;
|
|
}
|
|
|
|
function renderedCliResult(ok: boolean, command: string, renderedText: string, contentType: RenderedCliResult["contentType"] = "text/plain"): RenderedCliResult {
|
|
return { ok, command, renderedText: renderedText.endsWith("\n") ? renderedText : `${renderedText}\n`, contentType };
|
|
}
|
|
|
|
function renderCodexTraceHelp(raw: Record<string, unknown>): string {
|
|
const usage = stringArray(raw.usage);
|
|
const safety = stringArray(raw.safety);
|
|
const options = asRecord(raw.options) ?? {};
|
|
const lines = [
|
|
"Codex trace",
|
|
String(raw.description ?? ""),
|
|
"",
|
|
"Usage:",
|
|
...usage.map((line) => ` ${line}`),
|
|
"",
|
|
"Safety:",
|
|
...safety.map((line) => ` - ${line}`),
|
|
"",
|
|
"Options:",
|
|
...Object.entries(options).map(([key, value]) => ` ${key.padEnd(24)} ${String(value)}`),
|
|
];
|
|
return lines.filter((line, index) => line.length > 0 || lines[index - 1]?.length !== 0).join("\n");
|
|
}
|
|
|
|
function renderCodexTraceActive(raw: Record<string, unknown>, options: CodexTraceOptions): string {
|
|
const sessions = recordArray(raw.sessions);
|
|
if (sessions.length === 0) return "No active Codex session files found.";
|
|
const rows = sessions.map((session) => [
|
|
String(session.pid ?? "-"),
|
|
String(session.fd ?? "-"),
|
|
ageFromIso(stringValue(session.mtime)),
|
|
formatBytes(numberValue(session.bytes)),
|
|
String(session.sessionId ?? "-"),
|
|
truncateMiddle(String(session.path ?? "-"), options.output === "wide" ? 140 : 82),
|
|
]);
|
|
return [
|
|
renderTable(["PID", "FD", "AGE", "SIZE", "SESSION-ID", "FILE"], rows),
|
|
"",
|
|
"Next:",
|
|
" bun scripts/cli.ts codex trace grep --session <session-id> --pattern <regex>",
|
|
].join("\n");
|
|
}
|
|
|
|
function renderCodexTraceGrep(raw: Record<string, unknown>, options: CodexTraceOptions): string {
|
|
const results = recordArray(raw.results);
|
|
const header = `Matched ${String(raw.matchesReturned ?? 0)}/${String(raw.matchedTotal ?? 0)} events in ${String(raw.filesScanned ?? 0)} file(s), scanned ${String(raw.linesScanned ?? 0)} lines${raw.truncated === true ? " (truncated)" : ""}.`;
|
|
if (results.length === 0) return `${header}\nNo matching trace events found.`;
|
|
const rows = results.map((result) => [
|
|
shortIso(stringValue(result.timestamp)),
|
|
`${truncateMiddle(String(result.file ?? "-"), options.output === "wide" ? 96 : 42)}:${String(result.line ?? "-")}`,
|
|
truncateMiddle(traceResultItemLabel(result), 28),
|
|
signalLabel(asRecord(result.signals)),
|
|
truncateOneLine(String(result.summary ?? ""), options.output === "wide" ? 220 : 96),
|
|
]);
|
|
return [
|
|
header,
|
|
renderTable(["TIME", "LOCATION", "ITEM", "SIGNALS", "SUMMARY"], rows),
|
|
].join("\n");
|
|
}
|
|
|
|
function renderCodexTraceList(raw: Record<string, unknown>, options: CodexTraceOptions): string {
|
|
const files = recordArray(raw.files);
|
|
if (files.length === 0) return `No trace files found under ${String(raw.root ?? "-")}.`;
|
|
const rows = files.map((file) => [
|
|
String(file.sessionId ?? "-"),
|
|
truncateMiddle(String(file.path ?? "-"), options.output === "wide" ? 140 : 82),
|
|
String(file.kind ?? "-"),
|
|
formatBytes(numberValue(file.bytes)),
|
|
ageFromIso(stringValue(file.mtime)),
|
|
]);
|
|
const skipped = asRecord(raw.skipped) ?? {};
|
|
const skippedText = Object.entries(skipped).map(([key, value]) => `${key}=${String(value)}`).join(" ");
|
|
return [
|
|
`Root: ${String(raw.root ?? "-")}`,
|
|
renderTable(["SESSION-ID", "PATH", "KIND", "SIZE", "AGE"], rows),
|
|
skippedText.length > 0 ? `Skipped: ${skippedText}` : "",
|
|
Number(raw.omitted ?? 0) > 0 ? `Omitted: ${String(raw.omitted)}` : "",
|
|
].filter((line) => line.length > 0).join("\n");
|
|
}
|
|
|
|
function renderCodexTraceCollect(raw: Record<string, unknown>, options: CodexTraceOptions): string {
|
|
const files = recordArray(raw.files);
|
|
const headline = raw.dryRun === true ? "Dry-run collect" : "Collected";
|
|
const rows = files.map((file) => [
|
|
truncateMiddle(String(file.source ?? "-"), options.output === "wide" ? 120 : 72),
|
|
String(file.kind ?? "-"),
|
|
formatBytes(numberValue(file.bytes)),
|
|
]);
|
|
return [
|
|
`${headline}: ${String(raw.copiedCount ?? 0)} file(s), ${formatBytes(numberValue(raw.copiedBytes))}`,
|
|
`Output: ${String(raw.outputDir ?? "-")}`,
|
|
raw.manifest === null || raw.manifest === undefined ? "" : `Manifest: ${String(raw.manifest)}`,
|
|
rows.length > 0 ? renderTable(["SOURCE", "KIND", "SIZE"], rows) : "",
|
|
].filter((line) => line.length > 0).join("\n");
|
|
}
|
|
|
|
function renderCodexTraceShow(raw: Record<string, unknown>): string {
|
|
const policy = asRecord(raw.contentPolicy) ?? {};
|
|
const content = stringValue(raw.content);
|
|
const lines = [
|
|
`Name: ${String(raw.relativePath ?? raw.file ?? "-")}`,
|
|
`Session: ${String(raw.sessionId ?? "-")}`,
|
|
`Kind: ${String(raw.kind ?? "-")}`,
|
|
`Size: ${formatBytes(numberValue(raw.bytes))}`,
|
|
`Mode: ${String(policy.mode ?? "-")} bytes=${String(policy.bytesReturned ?? 0)} truncated=${String(policy.truncated ?? false)}`,
|
|
];
|
|
if (content !== null) lines.push("---", content);
|
|
else lines.push("Content: <not text-readable>");
|
|
return lines.join("\n");
|
|
}
|
|
|
|
function renderCodexTraceNames(raw: Record<string, unknown>): string {
|
|
const sessions = recordArray(raw.sessions);
|
|
if (sessions.length > 0) {
|
|
return sessions
|
|
.map((session) => String(session.sessionId ?? session.path ?? ""))
|
|
.filter((value) => value.length > 0)
|
|
.map((value) => `session/${value}`)
|
|
.join("\n");
|
|
}
|
|
const files = recordArray(raw.files);
|
|
if (files.length > 0) {
|
|
return files.map((file) => {
|
|
const sessionId = stringValue(file.sessionId);
|
|
return sessionId === null ? String(file.path ?? file.source ?? file.relativePath ?? "") : `session/${sessionId}`;
|
|
}).filter((line) => line.length > 0).join("\n");
|
|
}
|
|
const results = recordArray(raw.results);
|
|
if (results.length > 0) return results.map((result) => `${String(result.file ?? "")}:${String(result.line ?? "")}`).join("\n");
|
|
return "";
|
|
}
|
|
|
|
function traceResultItemLabel(result: Record<string, unknown>): string {
|
|
const eventClass = stringValue(result.class);
|
|
const tool = stringValue(result.tool);
|
|
if (eventClass === "tool-call" || eventClass === "tool-output") {
|
|
return tool === null ? eventClass : `${eventClass}/${tool}`;
|
|
}
|
|
return eventClass ?? String(result.item ?? result.type ?? "-");
|
|
}
|
|
|
|
function scanCodexTraceRoot(options: CodexTraceOptions): CodexTraceCandidate[] {
|
|
if (!existsSync(options.root)) return [];
|
|
const root = realpathSync(options.root);
|
|
const candidates: CodexTraceCandidate[] = [];
|
|
const walk = (dir: string, depth: number) => {
|
|
if (depth > options.maxDepth) return;
|
|
let entries;
|
|
try {
|
|
entries = readdirSync(dir, { withFileTypes: true });
|
|
} catch {
|
|
return;
|
|
}
|
|
for (const entry of entries) {
|
|
const fullPath = path.join(dir, entry.name);
|
|
const relativePath = path.relative(root, fullPath);
|
|
const normalizedRelative = normalizePath(relativePath);
|
|
if (entry.isSymbolicLink()) continue;
|
|
if (entry.isDirectory()) {
|
|
if (shouldSkipDirectory(normalizedRelative, entry.name, options)) continue;
|
|
walk(fullPath, depth + 1);
|
|
continue;
|
|
}
|
|
if (!entry.isFile()) continue;
|
|
let stats;
|
|
try {
|
|
stats = lstatSync(fullPath);
|
|
} catch {
|
|
continue;
|
|
}
|
|
const kind = classifyTraceKind(normalizedRelative, entry.name);
|
|
const skippedReason = skipReason(normalizedRelative, entry.name, kind, stats.size, options);
|
|
candidates.push({
|
|
path: fullPath,
|
|
relativePath,
|
|
kind,
|
|
bytes: stats.size,
|
|
mtimeMs: stats.mtimeMs,
|
|
included: skippedReason === null,
|
|
skippedReason,
|
|
});
|
|
}
|
|
};
|
|
walk(root, 0);
|
|
return candidates.sort((left, right) => right.mtimeMs - left.mtimeMs || left.relativePath.localeCompare(right.relativePath));
|
|
}
|
|
|
|
function activeCodexSessionFiles(rootReal: string): Record<string, unknown>[] {
|
|
const procDir = "/proc";
|
|
if (!existsSync(procDir)) return [];
|
|
const rows = new Map<string, Record<string, unknown>>();
|
|
let procEntries;
|
|
try {
|
|
procEntries = readdirSync(procDir, { withFileTypes: true });
|
|
} catch {
|
|
return [];
|
|
}
|
|
for (const procEntry of procEntries) {
|
|
if (!procEntry.isDirectory() || !/^\d+$/u.test(procEntry.name)) continue;
|
|
const pid = Number(procEntry.name);
|
|
const fdDir = path.join(procDir, procEntry.name, "fd");
|
|
let fdEntries;
|
|
try {
|
|
fdEntries = readdirSync(fdDir, { withFileTypes: true });
|
|
} catch {
|
|
continue;
|
|
}
|
|
const cmdline = readProcCmdline(pid);
|
|
if (!isCodexSessionProcess(cmdline)) continue;
|
|
for (const fdEntry of fdEntries) {
|
|
let target;
|
|
try {
|
|
target = readlinkSync(path.join(fdDir, fdEntry.name));
|
|
} catch {
|
|
continue;
|
|
}
|
|
const deletedSuffix = " (deleted)";
|
|
if (target.endsWith(deletedSuffix)) target = target.slice(0, -deletedSuffix.length);
|
|
if (!target.endsWith(".jsonl") || !isWithin(rootReal, target) || !normalizePath(path.relative(rootReal, target)).startsWith("sessions/")) continue;
|
|
const realTarget = safeRealpath(target);
|
|
if (realTarget === null || !isWithin(rootReal, realTarget)) continue;
|
|
let stats;
|
|
try {
|
|
stats = statSync(realTarget);
|
|
} catch {
|
|
continue;
|
|
}
|
|
const relativePath = path.relative(rootReal, realTarget);
|
|
const sessionId = extractSessionId(relativePath);
|
|
const key = `${pid}:${realTarget}`;
|
|
rows.set(key, {
|
|
pid,
|
|
fd: fdEntry.name,
|
|
path: relativePath,
|
|
sessionId,
|
|
bytes: stats.size,
|
|
mtime: stats.mtime.toISOString(),
|
|
command: truncateOneLine(cmdline, 180),
|
|
grepCommand: sessionId === null
|
|
? `bun scripts/cli.ts codex trace grep --file ${shellWord(relativePath)} --pattern <regex>`
|
|
: `bun scripts/cli.ts codex trace grep --session ${shellWord(sessionId)} --pattern <regex>`,
|
|
showCommand: sessionId === null
|
|
? `bun scripts/cli.ts codex trace show --file ${shellWord(relativePath)}`
|
|
: `bun scripts/cli.ts codex trace show --session ${shellWord(sessionId)}`,
|
|
});
|
|
}
|
|
}
|
|
return [...rows.values()].sort((left, right) => String(right.mtime).localeCompare(String(left.mtime)) || Number(left.pid) - Number(right.pid));
|
|
}
|
|
|
|
function grepTargetFiles(options: CodexTraceOptions, rootReal: string): CodexTraceCandidate[] {
|
|
if (options.session !== null) return [resolveSessionCandidate(rootReal, options.root, options.session)];
|
|
if (options.file !== null) {
|
|
return [candidateFromFile(rootReal, options.root, options.file, options.allowOutsideRoot)];
|
|
}
|
|
const active = activeCodexSessionFiles(rootReal)
|
|
.map((row) => String(row.path))
|
|
.filter((relativePath) => relativePath.length > 0)
|
|
.map((relativePath) => {
|
|
const filePath = path.join(rootReal, relativePath);
|
|
const stats = statSync(filePath);
|
|
return {
|
|
path: filePath,
|
|
relativePath,
|
|
kind: classifyTraceKind(relativePath, path.basename(filePath)),
|
|
bytes: stats.size,
|
|
mtimeMs: stats.mtimeMs,
|
|
included: true,
|
|
skippedReason: null,
|
|
} satisfies CodexTraceCandidate;
|
|
});
|
|
const scanned = options.allFiles
|
|
? scanCodexTraceRoot(options).filter((candidate) => candidate.included && isTextReadableTrace(candidate.kind, candidate.path))
|
|
: recentSessionCandidates(rootReal, options, options.fileLimit);
|
|
const byPath = new Map<string, CodexTraceCandidate>();
|
|
for (const candidate of [...active, ...scanned]) {
|
|
if (!isTextReadableTrace(candidate.kind, candidate.path)) continue;
|
|
byPath.set(candidate.path, candidate);
|
|
}
|
|
return [...byPath.values()].sort((left, right) => right.mtimeMs - left.mtimeMs).slice(0, options.fileLimit);
|
|
}
|
|
|
|
function candidateFromFile(rootReal: string, root: string, file: string, allowOutsideRoot = false): CodexTraceCandidate {
|
|
const filePath = resolveTraceFile(root, file);
|
|
const fileReal = safeRealpath(filePath);
|
|
if (fileReal === null) throw new Error(`codex trace file does not exist: ${filePath}`);
|
|
if (!allowOutsideRoot && !isWithin(rootReal, fileReal)) throw new Error("codex trace refuses file outside --root");
|
|
const stats = statSync(fileReal);
|
|
const relativePath = path.relative(rootReal, fileReal);
|
|
return {
|
|
path: fileReal,
|
|
relativePath,
|
|
kind: classifyTraceKind(relativePath, path.basename(fileReal)),
|
|
bytes: stats.size,
|
|
mtimeMs: stats.mtimeMs,
|
|
included: true,
|
|
skippedReason: null,
|
|
};
|
|
}
|
|
|
|
function resolveSessionCandidate(rootReal: string, root: string, rawSession: string): CodexTraceCandidate {
|
|
const session = rawSession.replace(/^session\//u, "").trim();
|
|
if (session.length === 0) throw new Error("codex trace --session requires a non-empty session id");
|
|
if (session.includes("/") || session.endsWith(".jsonl")) {
|
|
return candidateFromFile(rootReal, root, session);
|
|
}
|
|
const scanned = (sessionJsonlCandidatesByToken(rootReal, session) ?? sessionJsonlCandidates(rootReal))
|
|
.filter((candidate) => sessionCandidateMatches(candidate.relativePath, session));
|
|
const byPath = new Map<string, CodexTraceCandidate>();
|
|
for (const candidate of scanned) byPath.set(candidate.path, candidate);
|
|
const matches = [...byPath.values()].sort((left, right) => right.mtimeMs - left.mtimeMs);
|
|
if (matches.length === 0) throw new Error(`codex trace session not found under ${root}: ${session}`);
|
|
const exact = matches.filter((candidate) => sessionCandidateExact(candidate.relativePath, session));
|
|
if (exact.length === 1) return exact[0] as CodexTraceCandidate;
|
|
const prefix = matches.filter((candidate) => {
|
|
const id = extractSessionId(candidate.relativePath);
|
|
return id !== null && id.startsWith(session.toLowerCase());
|
|
});
|
|
if (prefix.length === 1) return prefix[0] as CodexTraceCandidate;
|
|
if (matches.length === 1) return matches[0] as CodexTraceCandidate;
|
|
const choices = matches.slice(0, 8).map((candidate) => ` ${extractSessionId(candidate.relativePath) ?? "-"} ${candidate.relativePath}`).join("\n");
|
|
throw new Error(`codex trace session id is ambiguous: ${session}\n${choices}`);
|
|
}
|
|
|
|
function recentSessionCandidates(rootReal: string, options: CodexTraceOptions, limit: number): CodexTraceCandidate[] {
|
|
return sessionJsonlCandidates(rootReal)
|
|
.filter((candidate) => candidate.bytes <= options.maxFileBytes || candidate.mtimeMs > Date.now() - 7 * 24 * 60 * 60 * 1000)
|
|
.sort((left, right) => right.mtimeMs - left.mtimeMs)
|
|
.slice(0, limit);
|
|
}
|
|
|
|
function sessionJsonlCandidates(rootReal: string): CodexTraceCandidate[] {
|
|
const sessionsRoot = path.join(rootReal, "sessions");
|
|
if (!existsSync(sessionsRoot)) return [];
|
|
const fast = sessionJsonlCandidatesFast(rootReal, sessionsRoot);
|
|
if (fast !== null) return fast;
|
|
const candidates: CodexTraceCandidate[] = [];
|
|
const walk = (dir: string, depth: number) => {
|
|
if (depth > 8) return;
|
|
let entries;
|
|
try {
|
|
entries = readdirSync(dir, { withFileTypes: true });
|
|
} catch {
|
|
return;
|
|
}
|
|
for (const entry of entries) {
|
|
const fullPath = path.join(dir, entry.name);
|
|
if (entry.isSymbolicLink()) continue;
|
|
if (entry.isDirectory()) {
|
|
walk(fullPath, depth + 1);
|
|
continue;
|
|
}
|
|
if (!entry.isFile() || !entry.name.endsWith(".jsonl")) continue;
|
|
let stats;
|
|
try {
|
|
stats = lstatSync(fullPath);
|
|
} catch {
|
|
continue;
|
|
}
|
|
const relativePath = path.relative(rootReal, fullPath);
|
|
candidates.push({
|
|
path: fullPath,
|
|
relativePath,
|
|
kind: "session-jsonl",
|
|
bytes: stats.size,
|
|
mtimeMs: stats.mtimeMs,
|
|
included: true,
|
|
skippedReason: null,
|
|
});
|
|
}
|
|
};
|
|
walk(sessionsRoot, 0);
|
|
return candidates;
|
|
}
|
|
|
|
function sessionJsonlCandidatesByToken(rootReal: string, token: string): CodexTraceCandidate[] | null {
|
|
if (!/^[A-Za-z0-9._-]+$/u.test(token)) return null;
|
|
const sessionsRoot = path.join(rootReal, "sessions");
|
|
if (!existsSync(sessionsRoot)) return [];
|
|
return sessionJsonlCandidatesFromRg(rootReal, sessionsRoot, `*${token}*.jsonl`);
|
|
}
|
|
|
|
function sessionJsonlCandidatesFast(rootReal: string, sessionsRoot: string): CodexTraceCandidate[] | null {
|
|
return sessionJsonlCandidatesFromRg(rootReal, sessionsRoot, "*.jsonl");
|
|
}
|
|
|
|
function sessionJsonlCandidatesFromRg(rootReal: string, sessionsRoot: string, glob: string): CodexTraceCandidate[] | null {
|
|
const result = spawnSync("rg", ["--files", "--glob", glob, sessionsRoot], { encoding: "utf8", maxBuffer: 8 * 1024 * 1024 });
|
|
if (result.error !== undefined || result.status !== 0) return null;
|
|
const candidates: CodexTraceCandidate[] = [];
|
|
for (const line of (result.stdout ?? "").split("\n")) {
|
|
if (line.length === 0) continue;
|
|
let stats;
|
|
try {
|
|
stats = lstatSync(line);
|
|
} catch {
|
|
continue;
|
|
}
|
|
const relativePath = path.relative(rootReal, line);
|
|
candidates.push({
|
|
path: line,
|
|
relativePath,
|
|
kind: "session-jsonl",
|
|
bytes: stats.size,
|
|
mtimeMs: stats.mtimeMs,
|
|
included: true,
|
|
skippedReason: null,
|
|
});
|
|
}
|
|
return candidates;
|
|
}
|
|
|
|
async function grepJsonlFile(
|
|
candidate: CodexTraceCandidate,
|
|
rootReal: string,
|
|
matcher: RegExp | null,
|
|
options: CodexTraceOptions,
|
|
results: Record<string, unknown>[],
|
|
limit: number,
|
|
): Promise<{ linesScanned: number; matchedTotal: number }> {
|
|
const fast = grepJsonlFileFast(candidate, rootReal, matcher, options, results, limit);
|
|
if (fast !== null) return fast;
|
|
let linesScanned = 0;
|
|
let matchedTotal = 0;
|
|
const toolCalls = new Map<string, ToolCallInfo>();
|
|
const toolMatcher = options.tool === null ? null : makeMatcher(options.tool, false);
|
|
const input = createReadStream(candidate.path, { encoding: "utf8" });
|
|
const reader = createInterface({ input, crlfDelay: Infinity });
|
|
try {
|
|
for await (const line of reader) {
|
|
linesScanned += 1;
|
|
const rawLineMatch = matcher === null ? false : matcher.test(line);
|
|
if (matcher !== null) matcher.lastIndex = 0;
|
|
if (!rawLineMatch && !options.deep && !shouldInspectTraceLine(line, options)) continue;
|
|
const event = parseJsonlEvent(line);
|
|
if (event === null) {
|
|
if (matcher === null) continue;
|
|
if (!rawLineMatch) continue;
|
|
matchedTotal += 1;
|
|
if (results.length < limit) {
|
|
results.push({
|
|
file: candidate.relativePath,
|
|
line: linesScanned,
|
|
timestamp: null,
|
|
type: "raw",
|
|
fields: ["raw"],
|
|
summary: truncateOneLine(redactTraceText(line), options.contextChars),
|
|
signals: traceSignals(line),
|
|
});
|
|
}
|
|
continue;
|
|
}
|
|
const eventClass = traceEventClass(event);
|
|
if (eventClass === "tool-call") {
|
|
const callId = traceCallId(event);
|
|
if (callId !== null) {
|
|
toolCalls.set(callId, {
|
|
name: traceToolName(event, null),
|
|
input: summarizeToolInput(event, Math.max(options.contextChars, 1000)),
|
|
line: linesScanned,
|
|
timestamp: typeof event.timestamp === "string" ? event.timestamp : null,
|
|
});
|
|
}
|
|
}
|
|
if (!options.includeSystem && event.type === "session_meta") continue;
|
|
if (!options.includeSystem && isBootstrapTraceEvent(event)) continue;
|
|
if (options.since !== null && typeof event.timestamp === "string" && event.timestamp < options.since) continue;
|
|
const callInfo = traceCallInfo(event, toolCalls);
|
|
const toolName = traceToolName(event, callInfo);
|
|
const failed = eventClass === "tool-output" && isFailedToolOutput(event);
|
|
if (!traceEventPassesKindFilters(eventClass, toolName, failed, toolMatcher, options)) continue;
|
|
const fields = traceEventFields(event);
|
|
const matchedFields: string[] = [];
|
|
const matchedValues: string[] = [];
|
|
if (matcher === null) {
|
|
matchedFields.push(failed ? "failed-output" : eventClass);
|
|
matchedValues.push(toolOutputText(event) ?? summarizeTraceEvent(event, Math.max(options.contextChars, 1000)));
|
|
} else {
|
|
for (const field of fields) {
|
|
const match = matcher.exec(field.value);
|
|
if (match !== null) {
|
|
matchedFields.push(field.name);
|
|
matchedValues.push(snippetAroundMatch(field.value, match.index, Math.max(options.contextChars, 1000)));
|
|
}
|
|
matcher.lastIndex = 0;
|
|
}
|
|
}
|
|
if (matchedFields.length === 0) continue;
|
|
matchedTotal += 1;
|
|
if (results.length >= limit) continue;
|
|
const summary = summarizeMatchedTraceEvent(event, fields, matcher, options, callInfo, failed);
|
|
results.push({
|
|
file: path.relative(rootReal, candidate.path),
|
|
line: linesScanned,
|
|
timestamp: typeof event.timestamp === "string" ? event.timestamp : null,
|
|
type: event.type,
|
|
class: eventClass,
|
|
item: traceEventItem(event),
|
|
tool: toolName,
|
|
failed,
|
|
fields: matchedFields,
|
|
summary,
|
|
signals: traceSignals(matchedValues.join(" ")),
|
|
});
|
|
}
|
|
} finally {
|
|
reader.close();
|
|
input.destroy();
|
|
}
|
|
return { linesScanned, matchedTotal };
|
|
}
|
|
|
|
function grepJsonlFileFast(
|
|
candidate: CodexTraceCandidate,
|
|
rootReal: string,
|
|
matcher: RegExp | null,
|
|
options: CodexTraceOptions,
|
|
results: Record<string, unknown>[],
|
|
limit: number,
|
|
): { linesScanned: number; matchedTotal: number } | null {
|
|
if (options.deep || !isTextReadableTrace(candidate.kind, candidate.path)) return null;
|
|
const rgPattern = fastGrepPattern(options);
|
|
if (rgPattern === null) return null;
|
|
const rgMaxCount = options.since === null ? Math.max(limit * 50, 200) : Math.max(limit * 200, 2000);
|
|
const rg = runRipgrepLines(candidate.path, rgPattern.pattern, rgPattern.fixed, rgMaxCount);
|
|
if (rg === null) return null;
|
|
let matchedTotal = 0;
|
|
const toolCalls = preloadToolCallsForMatches(candidate.path, rg, options);
|
|
const callCache = new Map<string, ToolCallInfo | null>();
|
|
const toolMatcher = options.tool === null ? null : makeMatcher(options.tool, false);
|
|
for (const match of rg) {
|
|
const event = parseJsonlEvent(match.text);
|
|
if (event === null) continue;
|
|
const eventClass = traceEventClass(event);
|
|
if (eventClass === "tool-call") {
|
|
const callId = traceCallId(event);
|
|
if (callId !== null) {
|
|
toolCalls.set(callId, {
|
|
name: traceToolName(event, null),
|
|
input: summarizeToolInput(event, Math.max(options.contextChars, 1000)),
|
|
line: match.line,
|
|
timestamp: typeof event.timestamp === "string" ? event.timestamp : null,
|
|
});
|
|
}
|
|
}
|
|
if (!options.includeSystem && event.type === "session_meta") continue;
|
|
if (!options.includeSystem && isBootstrapTraceEvent(event)) continue;
|
|
if (options.since !== null && typeof event.timestamp === "string" && event.timestamp < options.since) continue;
|
|
let callInfo = traceCallInfo(event, toolCalls);
|
|
const callId = traceCallId(event);
|
|
if (callInfo === null && eventClass === "tool-output" && callId !== null) {
|
|
if (!callCache.has(callId)) callCache.set(callId, findToolCallInfoByCallId(candidate.path, callId, match.line, options));
|
|
callInfo = callCache.get(callId) ?? null;
|
|
}
|
|
const toolName = traceToolName(event, callInfo);
|
|
const failed = eventClass === "tool-output" && isFailedToolOutput(event);
|
|
if (!traceEventPassesKindFilters(eventClass, toolName, failed, toolMatcher, options)) continue;
|
|
const fields = traceEventFields(event);
|
|
const matchedFields: string[] = [];
|
|
const matchedValues: string[] = [];
|
|
if (matcher === null) {
|
|
matchedFields.push(failed ? "failed-output" : eventClass);
|
|
matchedValues.push(toolOutputText(event) ?? summarizeTraceEvent(event, Math.max(options.contextChars, 1000)));
|
|
} else {
|
|
for (const field of fields) {
|
|
const fieldMatch = matcher.exec(field.value);
|
|
if (fieldMatch !== null) {
|
|
matchedFields.push(field.name);
|
|
matchedValues.push(snippetAroundMatch(field.value, fieldMatch.index, Math.max(options.contextChars, 1000)));
|
|
}
|
|
matcher.lastIndex = 0;
|
|
}
|
|
}
|
|
if (matchedFields.length === 0) continue;
|
|
matchedTotal += 1;
|
|
if (results.length >= limit) continue;
|
|
results.push({
|
|
file: path.relative(rootReal, candidate.path),
|
|
line: match.line,
|
|
timestamp: typeof event.timestamp === "string" ? event.timestamp : null,
|
|
type: event.type,
|
|
class: eventClass,
|
|
item: traceEventItem(event),
|
|
tool: toolName,
|
|
failed,
|
|
fields: matchedFields,
|
|
summary: summarizeMatchedTraceEvent(event, fields, matcher, options, callInfo, failed),
|
|
signals: traceSignals(matchedValues.join(" ")),
|
|
});
|
|
}
|
|
return { linesScanned: rg.length, matchedTotal };
|
|
}
|
|
|
|
function fastGrepPattern(options: CodexTraceOptions): { pattern: string; fixed: boolean } | null {
|
|
if (options.pattern !== null && options.pattern.length > 0) return { pattern: options.pattern, fixed: options.fixed };
|
|
if (options.failedOnly) {
|
|
return {
|
|
pattern: "Process exited with code [1-9][0-9]*|ok=false|\"ok\"\\s*:\\s*false|status=(blocked|failed|error)|\"status\"\\s*:\\s*\"(blocked|failed|error)\"|probe\\.error=auth-login-failed|auth-login-failed|Internal Server Error|Service Unavailable|Traceback|Unhandled exception|Exception:|Error:",
|
|
fixed: false,
|
|
};
|
|
}
|
|
return null;
|
|
}
|
|
|
|
function runRipgrepLines(filePath: string, pattern: string, fixed: boolean, maxCount: number): Array<{ line: number; text: string }> | null {
|
|
return runRipgrepLinesMany(filePath, [pattern], fixed, maxCount);
|
|
}
|
|
|
|
function runRipgrepLinesMany(filePath: string, patterns: string[], fixed: boolean, maxCount: number): Array<{ line: number; text: string }> | null {
|
|
if (patterns.length === 0) return [];
|
|
const args = ["--line-number", "--color", "never", "--ignore-case", "--max-count", String(maxCount)];
|
|
if (fixed) args.push("--fixed-strings");
|
|
for (const pattern of patterns) args.push("-e", pattern);
|
|
args.push("--", filePath);
|
|
const result = spawnSync("rg", args, { encoding: "utf8", maxBuffer: 16 * 1024 * 1024 });
|
|
if (result.error !== undefined) return null;
|
|
if (result.status !== 0 && result.status !== 1) return null;
|
|
const stdout = result.stdout ?? "";
|
|
if (stdout.length === 0) return [];
|
|
const rows: Array<{ line: number; text: string }> = [];
|
|
for (const rawLine of stdout.split("\n")) {
|
|
if (rawLine.length === 0) continue;
|
|
const separator = rawLine.indexOf(":");
|
|
if (separator <= 0) continue;
|
|
const line = Number(rawLine.slice(0, separator));
|
|
if (!Number.isInteger(line) || line <= 0) continue;
|
|
rows.push({ line, text: rawLine.slice(separator + 1) });
|
|
}
|
|
return rows;
|
|
}
|
|
|
|
function findToolCallInfoByCallId(filePath: string, callId: string, outputLine: number, options: CodexTraceOptions): ToolCallInfo | null {
|
|
const matches = runRipgrepLines(filePath, callId, true, 20);
|
|
if (matches === null) return null;
|
|
for (const match of matches) {
|
|
if (match.line >= outputLine) continue;
|
|
const event = parseJsonlEvent(match.text);
|
|
if (event === null || traceEventClass(event) !== "tool-call") continue;
|
|
return {
|
|
name: traceToolName(event, null),
|
|
input: summarizeToolInput(event, Math.max(options.contextChars, 1000)),
|
|
line: match.line,
|
|
timestamp: typeof event.timestamp === "string" ? event.timestamp : null,
|
|
};
|
|
}
|
|
return null;
|
|
}
|
|
|
|
function preloadToolCallsForMatches(filePath: string, matches: Array<{ line: number; text: string }>, options: CodexTraceOptions): Map<string, ToolCallInfo> {
|
|
const callIds = new Set<string>();
|
|
for (const match of matches) {
|
|
const event = parseJsonlEvent(match.text);
|
|
if (event === null || traceEventClass(event) !== "tool-output") continue;
|
|
const callId = traceCallId(event);
|
|
if (callId !== null) callIds.add(callId);
|
|
}
|
|
if (callIds.size === 0) return new Map<string, ToolCallInfo>();
|
|
return findToolCallInfosByCallIds(filePath, [...callIds], options);
|
|
}
|
|
|
|
function findToolCallInfosByCallIds(filePath: string, callIds: string[], options: CodexTraceOptions): Map<string, ToolCallInfo> {
|
|
const calls = new Map<string, ToolCallInfo>();
|
|
const matches = runRipgrepLinesMany(filePath, callIds, true, Math.max(callIds.length * 4, 20));
|
|
if (matches === null) return calls;
|
|
for (const match of matches) {
|
|
const event = parseJsonlEvent(match.text);
|
|
if (event === null || traceEventClass(event) !== "tool-call") continue;
|
|
const callId = traceCallId(event);
|
|
if (callId === null) continue;
|
|
calls.set(callId, {
|
|
name: traceToolName(event, null),
|
|
input: summarizeToolInput(event, Math.max(options.contextChars, 1000)),
|
|
line: match.line,
|
|
timestamp: typeof event.timestamp === "string" ? event.timestamp : null,
|
|
});
|
|
}
|
|
return calls;
|
|
}
|
|
|
|
function selectedCandidates(options: CodexTraceOptions, candidates: CodexTraceCandidate[]): CodexTraceCandidate[] {
|
|
return candidates.filter((item) => item.included).slice(0, options.limit);
|
|
}
|
|
|
|
function extractSessionId(relativePath: string): string | null {
|
|
const basename = path.basename(relativePath).replace(/\.jsonl$/iu, "");
|
|
const matches = basename.match(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/giu);
|
|
return matches === null || matches.length === 0 ? null : (matches[matches.length - 1] ?? null)?.toLowerCase() ?? null;
|
|
}
|
|
|
|
function sessionCandidateMatches(relativePath: string, rawSession: string): boolean {
|
|
const session = rawSession.toLowerCase();
|
|
const basename = path.basename(relativePath).replace(/\.jsonl$/iu, "").toLowerCase();
|
|
const normalized = normalizePath(relativePath).toLowerCase();
|
|
const id = extractSessionId(relativePath);
|
|
return sessionCandidateExact(relativePath, session)
|
|
|| (id !== null && (id.startsWith(session) || id.includes(session)))
|
|
|| basename.includes(session)
|
|
|| normalized.includes(session);
|
|
}
|
|
|
|
function sessionCandidateExact(relativePath: string, rawSession: string): boolean {
|
|
const session = rawSession.toLowerCase();
|
|
const basename = path.basename(relativePath).replace(/\.jsonl$/iu, "").toLowerCase();
|
|
const normalized = normalizePath(relativePath).toLowerCase();
|
|
const id = extractSessionId(relativePath);
|
|
return id === session || basename === session || normalized === session || normalized === `sessions/${session}`;
|
|
}
|
|
|
|
function classifyTraceKind(relativePath: string, basename: string): CodexTraceKind {
|
|
const normalized = normalizePath(relativePath);
|
|
if (/^sessions\/.+\.jsonl$/u.test(normalized)) return "session-jsonl";
|
|
if (basename === "history.jsonl") return "history-jsonl";
|
|
if (normalized.startsWith("shell_snapshots/")) return "shell-snapshot";
|
|
if (/\.log$/iu.test(basename)) return "log";
|
|
if (/trace/iu.test(normalized) && /\.(jsonl?|log|txt|md)$/iu.test(basename)) return "trace-named";
|
|
if (/\.jsonl$/iu.test(basename)) return "jsonl";
|
|
if (/\.sqlite$/iu.test(basename)) return "sqlite-db";
|
|
if (/\.sqlite-(?:wal|shm)$/iu.test(basename)) return "sqlite-sidecar";
|
|
return "unrecognized";
|
|
}
|
|
|
|
function skipReason(relativePath: string, basename: string, kind: CodexTraceKind, bytes: number, options: CodexTraceOptions): string | null {
|
|
if (kind === "unrecognized") return "unrecognized";
|
|
if (!options.includeSensitive && isSensitivePath(relativePath, basename)) return "sensitive-default-excluded";
|
|
if ((kind === "sqlite-db" || kind === "sqlite-sidecar") && !options.includeSqlite) return "sqlite-default-excluded";
|
|
if (bytes > options.maxFileBytes) return "over-max-file-bytes";
|
|
return null;
|
|
}
|
|
|
|
function shouldSkipDirectory(relativePath: string, basename: string, options: CodexTraceOptions): boolean {
|
|
if (options.includeCache) return false;
|
|
if (basename === "cache" || basename === ".tmp" || basename === "generated_images" || basename === "plugins" || basename === "skills") return true;
|
|
return relativePath.startsWith("cache/") || relativePath.startsWith(".tmp/") || relativePath.startsWith("generated_images/");
|
|
}
|
|
|
|
function isSensitivePath(relativePath: string, basename: string): boolean {
|
|
return /^auth\.json(?:\.|$)/iu.test(basename)
|
|
|| /^config\.toml(?:\.|$)/iu.test(basename)
|
|
|| /(^|\/)(auth|credential|secret|token|key)(\/|\.|-|_)/iu.test(relativePath);
|
|
}
|
|
|
|
function isTextReadableTrace(kind: CodexTraceKind, filePath: string): boolean {
|
|
if (kind === "sqlite-db" || kind === "sqlite-sidecar") return false;
|
|
return /\.(jsonl?|log|txt|md|toml|sh)$/iu.test(path.basename(filePath));
|
|
}
|
|
|
|
function candidateRow(candidate: CodexTraceCandidate): Record<string, unknown> {
|
|
const sessionId = extractSessionId(candidate.relativePath);
|
|
return {
|
|
path: candidate.relativePath,
|
|
sessionId,
|
|
kind: candidate.kind,
|
|
bytes: candidate.bytes,
|
|
mtime: new Date(candidate.mtimeMs).toISOString(),
|
|
showCommand: sessionId === null
|
|
? `bun scripts/cli.ts codex trace show --file ${shellWord(candidate.relativePath)}`
|
|
: `bun scripts/cli.ts codex trace show --session ${shellWord(sessionId)}`,
|
|
};
|
|
}
|
|
|
|
function candidateSummary(candidates: CodexTraceCandidate[], selected: CodexTraceCandidate[]): Record<string, unknown> {
|
|
const included = candidates.filter((item) => item.included);
|
|
const byKind: Record<string, number> = {};
|
|
for (const candidate of candidates) byKind[candidate.kind] = (byKind[candidate.kind] ?? 0) + 1;
|
|
return {
|
|
scannedFiles: candidates.length,
|
|
includedCandidates: included.length,
|
|
selectedFiles: selected.length,
|
|
selectedBytes: selected.reduce((sum, item) => sum + item.bytes, 0),
|
|
byKind,
|
|
};
|
|
}
|
|
|
|
function skippedSummary(candidates: CodexTraceCandidate[]): Record<string, number> {
|
|
const skipped: Record<string, number> = {};
|
|
for (const candidate of candidates) {
|
|
if (candidate.skippedReason === null) continue;
|
|
skipped[candidate.skippedReason] = (skipped[candidate.skippedReason] ?? 0) + 1;
|
|
}
|
|
return skipped;
|
|
}
|
|
|
|
function policySummary(options: CodexTraceOptions): Record<string, unknown> {
|
|
return {
|
|
limit: options.limit,
|
|
maxDepth: options.maxDepth,
|
|
maxFileBytes: options.maxFileBytes,
|
|
includeSqlite: options.includeSqlite,
|
|
includeSensitive: options.includeSensitive,
|
|
includeCache: options.includeCache,
|
|
grepDefaultScope: options.allFiles ? "all-included-files" : "active-and-recent-sessions",
|
|
grepParseMode: options.deep ? "deep-json-parse" : "raw-prefilter",
|
|
skippedByDefault: ["auth/config", "sqlite", "cache/.tmp/generated_images/plugins/skills"],
|
|
};
|
|
}
|
|
|
|
function parseJsonlEvent(line: string): Record<string, unknown> | null {
|
|
try {
|
|
const parsed = JSON.parse(line);
|
|
return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed as Record<string, unknown> : null;
|
|
} catch {
|
|
return null;
|
|
}
|
|
}
|
|
|
|
function isBootstrapTraceEvent(event: Record<string, unknown>): boolean {
|
|
const payload = asRecord(event.payload);
|
|
if (event.type === "session_meta") return true;
|
|
if (event.type !== "response_item") return false;
|
|
if (payload?.type !== "message") return false;
|
|
const content = Array.isArray(payload.content) ? payload.content : [];
|
|
const text = content
|
|
.map((item) => stringValue(asRecord(item)?.text))
|
|
.filter((value): value is string => value !== null)
|
|
.join("\n");
|
|
return text.includes("<permissions instructions>")
|
|
|| text.includes("<environment_context>")
|
|
|| text.includes("# AGENTS.md instructions")
|
|
|| text.includes("You are Codex, a coding agent")
|
|
|| text.includes("Knowledge cutoff:");
|
|
}
|
|
|
|
function traceEventFields(event: Record<string, unknown>): Array<{ name: string; value: string }> {
|
|
const payload = asRecord(event.payload);
|
|
const fields: Array<{ name: string; value: string }> = [];
|
|
addField(fields, "timestamp", event.timestamp);
|
|
addField(fields, "type", event.type);
|
|
addField(fields, "payload.type", payload?.type);
|
|
addField(fields, "payload.role", payload?.role);
|
|
addField(fields, "payload.name", payload?.name);
|
|
addField(fields, "message", payload?.message);
|
|
addField(fields, "arguments", payload?.arguments);
|
|
addField(fields, "output", payload?.output);
|
|
const content = Array.isArray(payload?.content) ? payload.content : [];
|
|
for (const [index, item] of content.entries()) {
|
|
const record = asRecord(item);
|
|
addField(fields, `content.${index}.type`, record?.type);
|
|
addField(fields, `content.${index}.text`, record?.text);
|
|
}
|
|
return fields;
|
|
}
|
|
|
|
function summarizeTraceEvent(event: Record<string, unknown>, maxChars: number): string {
|
|
const payload = asRecord(event.payload);
|
|
const eventType = stringValue(event.type);
|
|
const payloadType = stringValue(payload?.type);
|
|
if (eventType === "response_item" && payloadType === "function_call") {
|
|
const name = stringValue(payload?.name) ?? "function_call";
|
|
const args = parseJsonObject(stringValue(payload?.arguments) ?? "");
|
|
const cmd = stringValue(args?.cmd);
|
|
return truncateOneLine(redactTraceText(cmd === null ? `${name} ${stringValue(payload?.arguments) ?? ""}` : `${name}: ${cmd}`), maxChars);
|
|
}
|
|
if (eventType === "response_item" && payloadType === "function_call_output") {
|
|
const callId = stringValue(payload?.call_id);
|
|
const output = stringValue(payload?.output) ?? "";
|
|
return truncateOneLine(redactTraceText(`function_call_output${callId === null ? "" : ` ${callId}`}: ${output}`), maxChars);
|
|
}
|
|
if (eventType === "response_item" && payloadType === "message") {
|
|
const content = Array.isArray(payload?.content) ? payload.content : [];
|
|
const texts = content.map((item) => stringValue(asRecord(item)?.text)).filter((value): value is string => value !== null);
|
|
return truncateOneLine(redactTraceText(texts.join(" ")), maxChars);
|
|
}
|
|
if (eventType === "event_msg") {
|
|
return truncateOneLine(redactTraceText(stringValue(payload?.message) ?? JSON.stringify(payload ?? {})), maxChars);
|
|
}
|
|
return truncateOneLine(redactTraceText(JSON.stringify(event)), maxChars);
|
|
}
|
|
|
|
function summarizeMatchedTraceEvent(
|
|
event: Record<string, unknown>,
|
|
fields: Array<{ name: string; value: string }>,
|
|
matcher: RegExp | null,
|
|
options: CodexTraceOptions,
|
|
callInfo: ToolCallInfo | null,
|
|
failed: boolean,
|
|
): string {
|
|
const maxChars = options.contextChars;
|
|
const eventClass = traceEventClass(event);
|
|
if (eventClass === "tool-call") {
|
|
const toolName = traceToolName(event, callInfo) ?? "tool";
|
|
return truncateOneLine(`tool-call ${toolName} input: ${summarizeToolInput(event, maxChars)}`, maxChars + 120);
|
|
}
|
|
if (eventClass === "tool-output") {
|
|
const toolName = traceToolName(event, callInfo) ?? "tool";
|
|
const input = callInfo?.input ?? "<input unavailable>";
|
|
const output = toolOutputText(event) ?? "";
|
|
if (failed) {
|
|
const error = failureExcerpt(output, maxChars);
|
|
return truncateOneLine(`tool-output ${toolName} failed error: ${error} input: ${truncateOneLine(input, 220)}`, maxChars + 180);
|
|
}
|
|
if (!options.includeOutput) {
|
|
return truncateOneLine(`tool-output ${toolName} folded input: ${input}`, maxChars + 120);
|
|
}
|
|
}
|
|
const item = traceEventItem(event);
|
|
for (const field of fields) {
|
|
if (matcher === null) break;
|
|
const match = matcher.exec(field.value);
|
|
matcher.lastIndex = 0;
|
|
if (match === null || match.index < 0) continue;
|
|
const snippet = redactTraceText(snippetAroundMatch(field.value, match.index, maxChars));
|
|
return truncateOneLine(`${item === null ? String(event.type ?? "event") : item} ${field.name}: ${snippet}`, maxChars + 120);
|
|
}
|
|
return summarizeTraceEvent(event, maxChars);
|
|
}
|
|
|
|
function snippetAroundMatch(value: string, matchIndex: number, maxChars: number): string {
|
|
const halfWindow = Math.max(40, Math.floor(maxChars / 2));
|
|
const start = Math.max(0, matchIndex - halfWindow);
|
|
const end = Math.min(value.length, start + maxChars);
|
|
const prefix = start > 0 ? "…" : "";
|
|
const suffix = end < value.length ? "…" : "";
|
|
return `${prefix}${value.slice(start, end)}${suffix}`;
|
|
}
|
|
|
|
function traceEventItem(event: Record<string, unknown>): string | null {
|
|
const payload = asRecord(event.payload);
|
|
return stringValue(payload?.name) ?? stringValue(payload?.type) ?? stringValue(payload?.role);
|
|
}
|
|
|
|
function shouldInspectTraceLine(line: string, options: CodexTraceOptions): boolean {
|
|
if (line.includes('"function_call"')) return true;
|
|
if (options.failedOnly || options.toolsOnly || options.tool !== null) return line.includes('"function_call"') || line.includes('"function_call_output"');
|
|
if (options.messagesOnly) return line.includes('"message"');
|
|
return false;
|
|
}
|
|
|
|
function traceEventClass(event: Record<string, unknown>): "message" | "tool-call" | "tool-output" | "event" {
|
|
const payload = asRecord(event.payload);
|
|
if (event.type === "response_item" && payload?.type === "message") return "message";
|
|
if (event.type === "response_item" && payload?.type === "function_call") return "tool-call";
|
|
if (event.type === "response_item" && payload?.type === "function_call_output") return "tool-output";
|
|
return "event";
|
|
}
|
|
|
|
function traceCallId(event: Record<string, unknown>): string | null {
|
|
const payload = asRecord(event.payload);
|
|
return stringValue(payload?.call_id) ?? stringValue(payload?.id);
|
|
}
|
|
|
|
function traceCallInfo(event: Record<string, unknown>, toolCalls: Map<string, ToolCallInfo>): ToolCallInfo | null {
|
|
const callId = traceCallId(event);
|
|
return callId === null ? null : toolCalls.get(callId) ?? null;
|
|
}
|
|
|
|
function traceToolName(event: Record<string, unknown>, callInfo: ToolCallInfo | null): string | null {
|
|
const payload = asRecord(event.payload);
|
|
return stringValue(payload?.name) ?? callInfo?.name ?? null;
|
|
}
|
|
|
|
function summarizeToolInput(event: Record<string, unknown>, maxChars: number): string {
|
|
const payload = asRecord(event.payload);
|
|
const argsText = stringValue(payload?.arguments) ?? "";
|
|
const args = parseJsonObject(argsText);
|
|
const cmd = stringValue(args?.cmd);
|
|
const prompt = stringValue(args?.prompt);
|
|
const rendered = cmd ?? prompt ?? argsText;
|
|
return truncateOneLine(redactTraceText(rendered.length === 0 ? "<empty>" : rendered), maxChars);
|
|
}
|
|
|
|
function toolOutputText(event: Record<string, unknown>): string | null {
|
|
const payload = asRecord(event.payload);
|
|
return stringValue(payload?.output);
|
|
}
|
|
|
|
function isFailedToolOutput(event: Record<string, unknown>): boolean {
|
|
const output = toolOutputText(event) ?? "";
|
|
return /Process exited with code (?!0\b)\d+/iu.test(output)
|
|
|| /(?:^|\n)\s*ok=false\s*(?:\n|$)/iu.test(output)
|
|
|| /(?:^|\n)\s*status=(?:blocked|failed|error)\s*(?:\n|$)/iu.test(output)
|
|
|| /(?:^|\n)\s*probe\.error=auth-login-failed\s*(?:\n|$)/iu.test(output)
|
|
|| /(?:^|\n)\s*probe\.auth\.status(?:Text)?=(?:5\d\d|Internal Server Error|Service Unavailable)\s*(?:\n|$)/iu.test(output)
|
|
|| /Output:\s*\n\s*\{\s*\n\s*"ok"\s*:\s*false/iu.test(output)
|
|
|| /"error"\s*:\s*"auth-login-failed"/iu.test(output)
|
|
|| /"status"\s*:\s*"(?:blocked|failed|error)"/iu.test(output)
|
|
|| /"statusText"\s*:\s*"(?:Internal Server Error|Service Unavailable)"/iu.test(output)
|
|
|| /(?:^|\n)(?:Traceback|Unhandled exception|Exception:|Error:)[^\n]*/iu.test(output);
|
|
}
|
|
|
|
function failureExcerpt(output: string, maxChars: number): string {
|
|
const patterns = [
|
|
/Process exited with code (?!0\b)\d+[^\n]*/iu,
|
|
/(?:^|\n)\s*probe\.error=[^\n]+/iu,
|
|
/(?:^|\n)\s*probe\.auth\.statusText=[^\n]+/iu,
|
|
/"error"\s*:\s*"[^"]+"/iu,
|
|
/"name"\s*:\s*"(?:TimeoutError|[^"]*Error)"/iu,
|
|
/"message"\s*:\s*"[^"]*(?:Timeout|Error|failed|blocked)[^"]*"/iu,
|
|
/"statusText"\s*:\s*"[^"]+"/iu,
|
|
/auth-login-failed[^\n,}]*/iu,
|
|
/Internal Server Error|Service Unavailable|Traceback[^\n]*/iu,
|
|
/Error:[^\n]*/iu,
|
|
];
|
|
for (const pattern of patterns) {
|
|
const match = pattern.exec(output);
|
|
if (match !== null) return truncateOneLine(redactTraceText(match[0] ?? ""), maxChars);
|
|
}
|
|
return truncateOneLine(redactTraceText(output), maxChars);
|
|
}
|
|
|
|
function traceEventPassesKindFilters(
|
|
eventClass: "message" | "tool-call" | "tool-output" | "event",
|
|
toolName: string | null,
|
|
failed: boolean,
|
|
toolMatcher: RegExp | null,
|
|
options: CodexTraceOptions,
|
|
): boolean {
|
|
if (options.messagesOnly && eventClass !== "message") return false;
|
|
if (options.toolsOnly && eventClass !== "tool-call" && eventClass !== "tool-output") return false;
|
|
if (options.failedOnly && (eventClass !== "tool-output" || !failed)) return false;
|
|
if (toolMatcher !== null) {
|
|
const matched = toolName !== null && toolMatcher.test(toolName);
|
|
toolMatcher.lastIndex = 0;
|
|
if (!matched) return false;
|
|
}
|
|
if (eventClass === "tool-output" && !failed && !options.includeOutput && !options.failedOnly) return false;
|
|
return true;
|
|
}
|
|
|
|
function traceSignals(text: string): Record<string, boolean> {
|
|
return {
|
|
authLoginFailed: /auth-login-failed/iu.test(text),
|
|
status503: /status["']?\s*[:=]\s*503|Service Unavailable/iu.test(text),
|
|
sshHint: /UNIDESK_SSH_HINT|UNIDESK_SSH_TCP_POOL_HINT/iu.test(text),
|
|
transTimeoutHint: /UNIDESK_TRAN_TIMEOUT_HINT/iu.test(text),
|
|
sshTiming: /UNIDESK_SSH_TIMING/iu.test(text),
|
|
downloadProgress: /unidesk\.ssh\.download\.progress/iu.test(text),
|
|
};
|
|
}
|
|
|
|
function addField(fields: Array<{ name: string; value: string }>, name: string, value: unknown): void {
|
|
const text = stringValue(value);
|
|
if (text !== null && text.length > 0) fields.push({ name, value: text });
|
|
}
|
|
|
|
function asRecord(value: unknown): Record<string, unknown> | null {
|
|
return typeof value === "object" && value !== null && !Array.isArray(value) ? value as Record<string, unknown> : null;
|
|
}
|
|
|
|
function stringValue(value: unknown): string | null {
|
|
return typeof value === "string" ? value : null;
|
|
}
|
|
|
|
function numberValue(value: unknown): number | null {
|
|
return typeof value === "number" && Number.isFinite(value) ? value : null;
|
|
}
|
|
|
|
function stringArray(value: unknown): string[] {
|
|
return Array.isArray(value) ? value.map((item) => String(item)) : [];
|
|
}
|
|
|
|
function recordArray(value: unknown): Record<string, unknown>[] {
|
|
return Array.isArray(value) ? value.map(asRecord).filter((item): item is Record<string, unknown> => item !== null) : [];
|
|
}
|
|
|
|
function parseJsonObject(value: string): Record<string, unknown> | null {
|
|
if (value.trim().length === 0) return null;
|
|
try {
|
|
const parsed = JSON.parse(value);
|
|
return asRecord(parsed);
|
|
} catch {
|
|
return null;
|
|
}
|
|
}
|
|
|
|
function readFileSlice(filePath: string, start: number, length: number): string {
|
|
if (length <= 0) return "";
|
|
const fd = openSync(filePath, "r");
|
|
try {
|
|
const buffer = Buffer.alloc(length);
|
|
const bytesRead = readSync(fd, buffer, 0, length, start);
|
|
return buffer.subarray(0, bytesRead).toString("utf8");
|
|
} finally {
|
|
closeSync(fd);
|
|
}
|
|
}
|
|
|
|
function redactTraceText(text: string): string {
|
|
return text
|
|
.replace(/sk-[A-Za-z0-9_-]{16,}/gu, "sk-<redacted>")
|
|
.replace(/\b(?:ghp|github_pat)_[A-Za-z0-9_]{16,}/gu, "<github-token:redacted>")
|
|
.replace(/((?:api[_-]?key|token|authorization|password|secret)["']?\s*[:=]\s*["']?)[^"',\s}]+/giu, "$1<redacted>");
|
|
}
|
|
|
|
function truncateOneLine(value: string, maxChars: number): string {
|
|
const oneLine = value.replace(/\s+/gu, " ").trim();
|
|
return oneLine.length <= maxChars ? oneLine : `${oneLine.slice(0, Math.max(0, maxChars - 1))}…`;
|
|
}
|
|
|
|
function truncateMiddle(value: string, maxChars: number): string {
|
|
if (value.length <= maxChars) return value;
|
|
if (maxChars <= 8) return value.slice(0, maxChars);
|
|
const keep = maxChars - 1;
|
|
const left = Math.ceil(keep * 0.58);
|
|
const right = keep - left;
|
|
return `${value.slice(0, left)}…${value.slice(value.length - right)}`;
|
|
}
|
|
|
|
function renderTable(headers: string[], rows: string[][]): string {
|
|
const widths = headers.map((header, index) => Math.max(header.length, ...rows.map((row) => visibleLength(row[index] ?? ""))));
|
|
const renderRow = (row: string[]) => row.map((cell, index) => padRight(cell, widths[index] ?? 0)).join(" ").trimEnd();
|
|
return [renderRow(headers), ...rows.map(renderRow)].join("\n");
|
|
}
|
|
|
|
function padRight(value: string, width: number): string {
|
|
const length = visibleLength(value);
|
|
return length >= width ? value : `${value}${" ".repeat(width - length)}`;
|
|
}
|
|
|
|
function visibleLength(value: string): number {
|
|
return [...value].length;
|
|
}
|
|
|
|
function formatBytes(value: number | null): string {
|
|
if (value === null) return "-";
|
|
const units = ["B", "Ki", "Mi", "Gi"];
|
|
let size = value;
|
|
let unitIndex = 0;
|
|
while (size >= 1024 && unitIndex < units.length - 1) {
|
|
size /= 1024;
|
|
unitIndex += 1;
|
|
}
|
|
return unitIndex === 0 ? `${value}B` : `${size.toFixed(size >= 10 ? 0 : 1)}${units[unitIndex]}`;
|
|
}
|
|
|
|
function ageFromIso(value: string | null): string {
|
|
if (value === null) return "-";
|
|
const time = Date.parse(value);
|
|
if (!Number.isFinite(time)) return "-";
|
|
const seconds = Math.max(0, Math.floor((Date.now() - time) / 1000));
|
|
if (seconds < 60) return `${seconds}s`;
|
|
const minutes = Math.floor(seconds / 60);
|
|
if (minutes < 60) return `${minutes}m`;
|
|
const hours = Math.floor(minutes / 60);
|
|
if (hours < 48) return `${hours}h`;
|
|
return `${Math.floor(hours / 24)}d`;
|
|
}
|
|
|
|
function shortIso(value: string | null): string {
|
|
if (value === null) return "-";
|
|
return value.replace(/\.\d{3}Z$/u, "Z");
|
|
}
|
|
|
|
function signalLabel(signals: Record<string, unknown> | null): string {
|
|
if (signals === null) return "-";
|
|
const labels = [
|
|
signals.authLoginFailed === true ? "auth" : "",
|
|
signals.status503 === true ? "503" : "",
|
|
signals.sshHint === true ? "ssh-hint" : "",
|
|
signals.transTimeoutHint === true ? "timeout" : "",
|
|
signals.sshTiming === true ? "timing" : "",
|
|
signals.downloadProgress === true ? "download" : "",
|
|
].filter((label) => label.length > 0);
|
|
return labels.length === 0 ? "-" : labels.join(",");
|
|
}
|
|
|
|
function resolveTraceFile(root: string, file: string): string {
|
|
if (file === "~" || file.startsWith("~/")) return resolveUserPath(file);
|
|
if (path.isAbsolute(file)) return file;
|
|
return path.resolve(root, file);
|
|
}
|
|
|
|
function readProcCmdline(pid: number): string {
|
|
try {
|
|
const raw = readFileSync(path.join("/proc", String(pid), "cmdline"), "utf8");
|
|
return raw.split("\0").filter(Boolean).join(" ");
|
|
} catch {
|
|
return "";
|
|
}
|
|
}
|
|
|
|
function isCodexSessionProcess(cmdline: string): boolean {
|
|
const [executable] = cmdline.split(/\s+/u).filter(Boolean);
|
|
if (executable === undefined) return false;
|
|
return path.basename(executable) === "codex";
|
|
}
|
|
|
|
function makeMatcher(pattern: string, fixed: boolean): RegExp {
|
|
const source = fixed ? escapeRegExp(pattern) : pattern;
|
|
try {
|
|
return new RegExp(source, "iu");
|
|
} catch (error) {
|
|
if (fixed) throw error;
|
|
return new RegExp(escapeRegExp(pattern), "iu");
|
|
}
|
|
}
|
|
|
|
function escapeRegExp(value: string): string {
|
|
return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
|
|
}
|
|
|
|
function parseOutputMode(raw: string | undefined, wide: boolean): CodexTraceOutput {
|
|
if (wide) return "wide";
|
|
if (raw === undefined) return "text";
|
|
if (raw === "json" || raw === "yaml" || raw === "name" || raw === "wide") return raw;
|
|
throw new Error(`codex trace output mode must be one of: json, yaml, name, wide; got ${raw}`);
|
|
}
|
|
|
|
function defaultCodexRoot(): string {
|
|
return path.join(homedir(), ".codex");
|
|
}
|
|
|
|
function resolveUserPath(value: string): string {
|
|
if (value === "~") return homedir();
|
|
if (value.startsWith("~/")) return path.join(homedir(), value.slice(2));
|
|
return path.resolve(value);
|
|
}
|
|
|
|
function safeRealpath(value: string): string | null {
|
|
try {
|
|
return realpathSync(value);
|
|
} catch {
|
|
return null;
|
|
}
|
|
}
|
|
|
|
function isWithin(root: string, target: string): boolean {
|
|
const relative = path.relative(root, target);
|
|
return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
|
|
}
|
|
|
|
function normalizePath(value: string): string {
|
|
return value.split(path.sep).join("/");
|
|
}
|
|
|
|
function timestampForPath(): string {
|
|
return new Date().toISOString().replace(/[:.]/gu, "-");
|
|
}
|
|
|
|
function shellWord(value: string): string {
|
|
return JSON.stringify(value);
|
|
}
|
|
|
|
function hasFlag(args: string[], name: string): boolean {
|
|
return args.includes(name);
|
|
}
|
|
|
|
function optionValue(args: string[], name: string): string | undefined {
|
|
const index = args.indexOf(name);
|
|
if (index === -1) return undefined;
|
|
const value = args[index + 1];
|
|
if (value === undefined || value.length === 0 || value.startsWith("--")) throw new Error(`${name} requires a value`);
|
|
return value;
|
|
}
|
|
|
|
function positiveIntegerOption(args: string[], name: string, defaultValue: number, maxValue: number): number {
|
|
const raw = optionValue(args, name);
|
|
if (raw === undefined) return defaultValue;
|
|
const value = Number(raw);
|
|
if (!Number.isInteger(value) || value <= 0) throw new Error(`${name} must be a positive integer`);
|
|
return Math.min(value, maxValue);
|
|
}
|
|
|
|
function bytesOption(args: string[], name: string, defaultValue: number, maxValue: number): number {
|
|
const raw = optionValue(args, name);
|
|
if (raw === undefined) return defaultValue;
|
|
const match = /^(\d+)(?:\s*(b|kib|kb|mib|mb|gib|gb))?$/iu.exec(raw.trim());
|
|
if (match === null) throw new Error(`${name} must be a byte count such as 12000000 or 25MiB`);
|
|
const base = Number(match[1]);
|
|
const unit = (match[2] ?? "b").toLowerCase();
|
|
const multiplier = unit === "b" ? 1 : unit === "kb" || unit === "kib" ? 1024 : unit === "mb" || unit === "mib" ? 1024 * 1024 : 1024 * 1024 * 1024;
|
|
return Math.min(base * multiplier, maxValue);
|
|
}
|
|
|
|
function assertKnownOptions(args: string[], spec: { flags: string[]; values: string[] }): void {
|
|
const flags = new Set(spec.flags);
|
|
const values = new Set(spec.values);
|
|
for (let index = 0; index < args.length; index += 1) {
|
|
const arg = args[index] ?? "";
|
|
if (!arg.startsWith("--") && arg !== "-h") continue;
|
|
if (flags.has(arg)) continue;
|
|
if (values.has(arg)) {
|
|
index += 1;
|
|
continue;
|
|
}
|
|
throw new Error(`unknown codex trace option: ${arg}`);
|
|
}
|
|
}
|