@gajae-code/coding-agent 0.8.2 → 0.9.1

package/src/task/token-log.test.ts

@@ -0,0 +1,188 @@
+import { describe, expect, it } from "bun:test";
+import { appendFile, mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { GJC_SESSION_ACTIVITY_FILE, sessionRoot } from "../gjc-runtime/session-layout";
+import {
+	computeCacheHitRate,
+	persistTaskTokenLog,
+	readTaskTokenLogs,
+	resolveTaskTokenLogDir,
+	taskTokenLogFromChat,
+	taskTokenLogFromUsage,
+} from "./token-log";
+
+async function withTempDir<T>(fn: (dir: string) => Promise<T>): Promise<T> {
+	const dir = await mkdtemp(join(tmpdir(), "gjc-token-log-"));
+	try {
+		return await fn(dir);
+	} finally {
+		await rm(dir, { recursive: true, force: true });
+	}
+}
+
+describe("task token log", () => {
+	it("maps raw chat buckets without folding cache into input", () => {
+		const log = taskTokenLogFromChat(
+			{
+				inputTokens: 100,
+				outputTokens: 20,
+				cachedInputTokens: 30,
+				cacheWriteTokens: 5,
+				costUsd: 0.25,
+			},
+			{
+				subagentId: "root",
+				agent: "main",
+				turn: 1,
+				at: "2026-01-01T00:00:00.000Z",
+				model: "model-a",
+			},
+		);
+
+		expect(log.input).toBe(100);
+		expect(log.output).toBe(20);
+		expect(log.cacheRead).toBe(30);
+		expect(log.cacheWrite).toBe(5);
+		expect(log.totalTokens).toBe(155);
+		expect(log.cost).toBe(0.25);
+		expect(log.model).toBe("model-a");
+	});
+
+	it("maps zero-cache chat buckets without inventing cache tokens", () => {
+		const log = taskTokenLogFromChat(
+			{ inputTokens: 7, outputTokens: 3, cachedInputTokens: 0, cacheWriteTokens: 0 },
+			{ subagentId: "root", turn: 2, at: "2026-01-01T00:00:02.000Z" },
+		);
+
+		expect(log.input).toBe(7);
+		expect(log.output).toBe(3);
+		expect(log.cacheRead).toBe(0);
+		expect(log.cacheWrite).toBe(0);
+		expect(log.totalTokens).toBe(10);
+	});
+
+	it("keeps large cache-only reads out of input and hits the cache-rate upper boundary", () => {
+		const log = taskTokenLogFromChat(
+			{ inputTokens: 0, outputTokens: 2, cachedInputTokens: 1_000_000_000, cacheWriteTokens: 0 },
+			{ subagentId: "root", turn: 3, at: "2026-01-01T00:00:03.000Z" },
+		);
+
+		expect(log.input).toBe(0);
+		expect(log.output).toBe(2);
+		expect(log.cacheRead).toBe(1_000_000_000);
+		expect(log.cacheWrite).toBe(0);
+		expect(log.totalTokens).toBe(1_000_000_002);
+		expect(computeCacheHitRate(log.input, log.cacheRead)).toBe(1);
+	});
+
+	it("persists and reads a jsonl round trip", async () => {
+		await withTempDir(async dir => {
+			const first = taskTokenLogFromChat(
+				{ inputTokens: 1, outputTokens: 2, cachedInputTokens: 3, cacheWriteTokens: 4 },
+				{ subagentId: "root", turn: 1, at: "2026-01-01T00:00:00.000Z" },
+			);
+			const second = taskTokenLogFromChat(
+				{ inputTokens: 5, outputTokens: 6, cachedInputTokens: 7, cacheWriteTokens: 8 },
+				{ subagentId: "child", agent: "executor", turn: 1, at: "2026-01-01T00:00:01.000Z" },
+			);
+
+			await persistTaskTokenLog(first, { dir });
+			await persistTaskTokenLog(second, { dir });
+
+			expect(await readTaskTokenLogs(dir)).toEqual([first, second]);
+		});
+	});
+
+	it("prefers the current session manager over a stale latest-active session", async () => {
+		await withTempDir(async cwd => {
+			const currentSessionId = "current-session";
+			const staleSessionId = "stale-session";
+			for (const [sessionId, updatedAt] of [
+				[currentSessionId, "2026-01-01T00:00:00.000Z"],
+				[staleSessionId, "2026-01-01T00:00:10.000Z"],
+			] as const) {
+				const markerPath = join(sessionRoot(cwd, sessionId), GJC_SESSION_ACTIVITY_FILE);
+				await mkdir(join(markerPath, ".."), { recursive: true });
+				await writeFile(
+					markerPath,
+					`${JSON.stringify({ session_id: sessionId, updated_at: updatedAt })}\n`,
+					"utf-8",
+				);
+			}
+
+			await expect(resolveTaskTokenLogDir(cwd, undefined, "")).resolves.toBe(
+				join(sessionRoot(cwd, staleSessionId), "token-logs"),
+			);
+			await expect(resolveTaskTokenLogDir(cwd, { getSessionId: () => currentSessionId }, "")).resolves.toBe(
+				join(sessionRoot(cwd, currentSessionId), "token-logs"),
+			);
+		});
+	});
+
+	it("missing token-log file reads as empty", async () => {
+		await withTempDir(async dir => {
+			expect(await readTaskTokenLogs(dir)).toEqual([]);
+		});
+	});
+
+	it("subtracts cache from the aggregate ChatUsageSnapshot input bucket", () => {
+		// buildUsageSnapshot sets inputTokens = rawInput + cacheRead + cacheWrite.
+		// taskTokenLogFromUsage must recover the raw (cache-excluded) input.
+		const log = taskTokenLogFromUsage(
+			{
+				inputTokens: 135,
+				outputTokens: 20,
+				totalTokens: 155,
+				cachedInputTokens: 30,
+				cacheWriteTokens: 5,
+				reasoningOutputTokens: 0,
+			},
+			{ subagentId: "root", turn: 1, at: "2026-01-01T00:00:00.000Z", cost: { usd: 0.5 } },
+		);
+
+		expect(log.input).toBe(100);
+		expect(log.cacheRead).toBe(30);
+		expect(log.cacheWrite).toBe(5);
+		expect(log.output).toBe(20);
+		expect(log.totalTokens).toBe(155);
+		expect(log.cost).toBe(0.5);
+	});
+
+	it("clamps aggregate input underflow to zero", () => {
+		const log = taskTokenLogFromUsage(
+			{
+				inputTokens: 10,
+				outputTokens: 1,
+				totalTokens: 10,
+				cachedInputTokens: 8,
+				cacheWriteTokens: 5,
+				reasoningOutputTokens: undefined,
+			},
+			{ subagentId: "root", turn: 1, at: "2026-01-01T00:00:00.000Z" },
+		);
+
+		expect(log.input).toBe(0);
+	});
+
+	it("skips a torn or corrupt jsonl line instead of throwing", async () => {
+		await withTempDir(async dir => {
+			const valid = taskTokenLogFromChat(
+				{ inputTokens: 1, outputTokens: 2, cachedInputTokens: 3, cacheWriteTokens: 4 },
+				{ subagentId: "root", turn: 1, at: "2026-01-01T00:00:00.000Z" },
+			);
+			await persistTaskTokenLog(valid, { dir });
+			// A partially-flushed / corrupt trailing line must not abort the read.
+			await appendFile(join(dir, "token-log.jsonl"), '{"subagentId":"root","turn":2,', "utf-8");
+
+			expect(await readTaskTokenLogs(dir)).toEqual([valid]);
+		});
+	});
+
+	it("throws when a non-empty log has no valid entries", async () => {
+		await withTempDir(async dir => {
+			await appendFile(join(dir, "token-log.jsonl"), "not json\n{}\n", "utf-8");
+			await expect(readTaskTokenLogs(dir)).rejects.toThrow(/corrupt token-log/);
+		});
+	});
+});

package/src/task/token-log.ts

@@ -0,0 +1,179 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { ChatUsageSnapshot, CostEstimate } from "@gajae-code/agent-core";
+import { sessionRoot } from "../gjc-runtime/session-layout";
+import { resolveGjcSessionForRead, SessionResolutionError } from "../gjc-runtime/session-resolution";
+import type { TaskTokenLog, TaskTokenMetrics } from "./types";
+
+const TOKEN_LOG_FILE = "token-log.jsonl";
+
+export interface TaskTokenLogChatBuckets {
+	readonly inputTokens: number;
+	readonly outputTokens: number;
+	readonly cachedInputTokens: number;
+	readonly cacheWriteTokens: number;
+	readonly costUsd?: number;
+}
+
+export interface TaskTokenLogSessionManager {
+	getSessionId(): string;
+}
+
+export interface TaskTokenLogContext {
+	readonly subagentId: string;
+	readonly agent?: string;
+	readonly turn: number;
+	readonly at: string;
+	readonly model?: string;
+}
+
+export function taskTokenLogFromChat(chat: TaskTokenLogChatBuckets, ctx: TaskTokenLogContext): TaskTokenLog {
+	const input = chat.inputTokens;
+	const output = chat.outputTokens;
+	const cacheRead = chat.cachedInputTokens;
+	const cacheWrite = chat.cacheWriteTokens;
+	return {
+		subagentId: ctx.subagentId,
+		...(ctx.agent ? { agent: ctx.agent } : {}),
+		turn: ctx.turn,
+		at: ctx.at,
+		input,
+		output,
+		cacheRead,
+		cacheWrite,
+		totalTokens: input + output + cacheRead + cacheWrite,
+		...(chat.costUsd !== undefined ? { cost: chat.costUsd } : {}),
+		...(ctx.model ? { model: ctx.model } : {}),
+	};
+}
+
+export function taskTokenLogFromUsage(
+	usage: ChatUsageSnapshot,
+	ctx: TaskTokenLogContext & { readonly cost?: CostEstimate },
+): TaskTokenLog {
+	const costUsd = ctx.cost && "usd" in ctx.cost ? ctx.cost.usd : undefined;
+	const cacheRead = usage.cachedInputTokens ?? 0;
+	const cacheWrite = usage.cacheWriteTokens ?? 0;
+	// `ChatUsageSnapshot.inputTokens` is the aggregate input-class bucket
+	// (raw input + cacheRead + cacheWrite; see buildUsageSnapshot in the agent
+	// telemetry layer). `TaskTokenLog.input` must be the cost-bearing bucket that
+	// EXCLUDES cache, so subtract the cache buckets back out (clamped at 0).
+	const input = Math.max(0, usage.inputTokens - cacheRead - cacheWrite);
+	return taskTokenLogFromChat(
+		{
+			inputTokens: input,
+			outputTokens: usage.outputTokens,
+			cachedInputTokens: cacheRead,
+			cacheWriteTokens: cacheWrite,
+			...(costUsd !== undefined ? { costUsd } : {}),
+		},
+		ctx,
+	);
+}
+
+export async function resolveTaskTokenLogDir(
+	cwd: string,
+	sessionManager: TaskTokenLogSessionManager | undefined,
+	envSessionId: string | undefined = process.env.GJC_SESSION_ID,
+): Promise<string | undefined> {
+	// Prefer the canonical SessionManager id so root turns land in the SAME
+	// `<session>/token-logs` dir the task executor uses for subagent turns and
+	// that `gjc --fixture <id>` reads from. Fall back to the env/latest-active
+	// session only when no manager id is available (e.g. lifecycle launches where
+	// the SDK adopts a pre-allocated id internally). Never let a best-effort
+	// telemetry side channel crash startup — swallow every SessionResolutionError.
+	const managerId = sessionManager?.getSessionId();
+	if (managerId) return path.join(sessionRoot(cwd, managerId), "token-logs");
+	try {
+		const session = await resolveGjcSessionForRead(cwd, { envSessionId });
+		return path.join(session.sessionRoot, "token-logs");
+	} catch (error) {
+		if (error instanceof SessionResolutionError) return undefined;
+		throw error;
+	}
+}
+export async function persistTaskTokenLog(entry: TaskTokenLog, opts: { dir: string }): Promise<void> {
+	await fs.mkdir(opts.dir, { recursive: true });
+	await fs.appendFile(path.join(opts.dir, TOKEN_LOG_FILE), `${JSON.stringify(entry)}\n`, "utf-8");
+}
+
+export async function readTaskTokenLogs(dir: string): Promise<TaskTokenLog[]> {
+	let raw: string;
+	try {
+		raw = await fs.readFile(path.join(dir, TOKEN_LOG_FILE), "utf-8");
+	} catch (error) {
+		if (isNodeError(error) && error.code === "ENOENT") return [];
+		throw error;
+	}
+	const logs: TaskTokenLog[] = [];
+	let skipped = 0;
+	for (const line of raw.split("\n")) {
+		if (line.trim().length === 0) continue;
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(line);
+		} catch {
+			// Skip a torn/partially-flushed tail line rather than aborting the
+			// entire read; concurrent appends can leave an incomplete final line.
+			skipped += 1;
+			continue;
+		}
+		if (isTaskTokenLog(parsed)) logs.push(parsed);
+		else skipped += 1;
+	}
+	// A torn tail line alongside valid entries is tolerated, but a non-empty file
+	// that yields zero valid entries is corrupt — surface it loudly rather than
+	// returning [] (which a caller would render as a misleading all-zero report).
+	if (logs.length === 0 && skipped > 0) {
+		throw new Error(`corrupt token-log: ${skipped} unparseable line(s) and no valid entries in ${dir}`);
+	}
+	return logs;
+}
+
+export function computeTaskTokenMetrics(logs: readonly TaskTokenLog[]): TaskTokenMetrics {
+	let inputTokens = 0;
+	let outputTokens = 0;
+	let cacheReadTokens = 0;
+	let cacheWriteTokens = 0;
+	let totalTokens = 0;
+	for (const log of logs) {
+		inputTokens += log.input;
+		outputTokens += log.output;
+		cacheReadTokens += log.cacheRead;
+		cacheWriteTokens += log.cacheWrite;
+		totalTokens += log.totalTokens;
+	}
+	return {
+		turns: logs.length,
+		inputTokens,
+		outputTokens,
+		cacheReadTokens,
+		cacheWriteTokens,
+		totalTokens,
+		cacheHitRate: computeCacheHitRate(inputTokens, cacheReadTokens),
+	};
+}
+
+export function computeCacheHitRate(input: number, cacheRead: number): number {
+	const denominator = input + cacheRead;
+	return denominator <= 0 ? 0 : cacheRead / denominator;
+}
+
+function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+	return error instanceof Error && "code" in error;
+}
+
+function isTaskTokenLog(value: unknown): value is TaskTokenLog {
+	if (value === null || typeof value !== "object") return false;
+	const record = value as Record<string, unknown>;
+	return (
+		typeof record.subagentId === "string" &&
+		typeof record.turn === "number" &&
+		typeof record.at === "string" &&
+		typeof record.input === "number" &&
+		typeof record.output === "number" &&
+		typeof record.cacheRead === "number" &&
+		typeof record.cacheWrite === "number" &&
+		typeof record.totalTokens === "number"
+	);
+}