@sayknow-cli/coding-agent 0.3.7 → 0.3.9

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 "@sayknow-cli/agent-core";
+import { sessionRoot } from "../skc-runtime/session-layout";
+import { resolveSkcSessionForRead, SessionResolutionError } from "../skc-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.SKC_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 `skc --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 resolveSkcSessionForRead(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"
+	);
+}

package/src/tools/bisect.ts

@@ -0,0 +1,367 @@
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@sayknow-cli/agent-core";
+import { prompt } from "@sayknow-cli/utils";
+import * as z from "zod/v4";
+import bisectDescription from "../prompts/tools/bisect.md" with { type: "text" };
+import * as git from "../utils/git";
+import type { ToolSession } from ".";
+import type { OutputMeta } from "./output-meta";
+import { ToolAbortError, ToolError, throwIfAborted } from "./tool-errors";
+import { toolResult } from "./tool-result";
+
+const DEFAULT_MAX_STEPS = 40;
+const DEFAULT_STEP_TIMEOUT_MS = 10 * 60 * 1000;
+/** git bisect run convention: a predicate exiting 125 means "cannot test this revision". */
+const SKIP_EXIT_CODE = 125;
+
+const bisectSchema = z.object({
+	good: z
+		.string()
+		.min(1)
+		.describe("A known-good commit-ish (must be an ancestor of `bad`) where the predicate passes."),
+	bad: z
+		.string()
+		.min(1)
+		.default("HEAD")
+		.describe("A known-bad commit-ish (defaults to HEAD) where the predicate fails."),
+	run: z
+		.string()
+		.min(1)
+		.describe("Shell command evaluated at each revision. Exit 0 = good, 125 = skip, any other non-zero = bad."),
+	invert: z
+		.boolean()
+		.default(false)
+		.describe("Find the commit that FIXED the behavior instead of the one that broke it (exit 0 is treated as bad)."),
+	maxSteps: z
+		.number()
+		.int()
+		.positive()
+		.max(1000)
+		.default(DEFAULT_MAX_STEPS)
+		.describe("Maximum bisection steps before giving up."),
+	stepTimeoutMs: z
+		.number()
+		.int()
+		.positive()
+		.default(DEFAULT_STEP_TIMEOUT_MS)
+		.describe("Per-step timeout in milliseconds; a timed-out step is treated as a skip."),
+});
+
+type BisectParams = z.infer<typeof bisectSchema>;
+
+export type BisectVerdict = "good" | "bad" | "skip";
+
+export interface BisectStep {
+	rev: string;
+	verdict: BisectVerdict;
+}
+
+export interface BisectMarkResult {
+	exitCode: number;
+	output: string;
+}
+
+export interface BisectControllerDeps {
+	maxSteps: number;
+	/** SHA of the revision git currently has checked out. */
+	currentRev: () => Promise<string>;
+	/** Evaluate the predicate at the checked-out revision. */
+	evaluate: (rev: string) => Promise<BisectVerdict>;
+	/** Apply the verdict via `git bisect good|bad|skip` and return the raw result. */
+	mark: (verdict: BisectVerdict) => Promise<BisectMarkResult>;
+}
+
+export interface BisectOutcome {
+	culprit: string | null;
+	steps: BisectStep[];
+	concluded: boolean;
+	reason?: string;
+}
+
+export interface BisectToolDetails {
+	meta?: OutputMeta;
+	culprit: string | null;
+	invert: boolean;
+	concluded: boolean;
+	steps: BisectStep[];
+	author?: string;
+	date?: string;
+	subject?: string;
+	reason?: string;
+}
+
+const FIRST_BAD_RE = /^([0-9a-f]{7,40}) is the first bad commit$/m;
+const ONLY_SKIPPED_RE = /only '?skip'?ped commits left to test/i;
+
+/** Parse the culprit SHA from `git bisect good|bad` output, or null when not yet converged. */
+export function parseFirstBadCommit(output: string): string | null {
+	const match = FIRST_BAD_RE.exec(output);
+	return match ? match[1]! : null;
+}
+
+/**
+ * Map a predicate exit code to a bisect verdict. `invert` swaps the good/bad
+ * mapping (to hunt for a fixing commit) but never reinterprets a skip.
+ */
+export function classifyExit(exitCode: number, invert: boolean): BisectVerdict {
+	if (exitCode === SKIP_EXIT_CODE) return "skip";
+	const verdict: BisectVerdict = exitCode === 0 ? "good" : "bad";
+	if (!invert) return verdict;
+	return verdict === "good" ? "bad" : "good";
+}
+
+/**
+ * Drive the bisect loop. Pure orchestration — every git/predicate effect is
+ * injected — so it can be exercised deterministically without a real repo.
+ */
+export async function runBisectController(deps: BisectControllerDeps, signal?: AbortSignal): Promise<BisectOutcome> {
+	const steps: BisectStep[] = [];
+	for (let step = 0; step < deps.maxSteps; step += 1) {
+		throwIfAborted(signal);
+		const rev = await deps.currentRev();
+		const verdict = await deps.evaluate(rev);
+		steps.push({ rev, verdict });
+		const marked = await deps.mark(verdict);
+		if (marked.exitCode !== 0) {
+			return {
+				culprit: null,
+				steps,
+				concluded: false,
+				reason: marked.output.trim() || `git bisect ${verdict} failed with exit code ${marked.exitCode}`,
+			};
+		}
+		const culprit = parseFirstBadCommit(marked.output);
+		if (culprit) return { culprit, steps, concluded: true };
+		if (ONLY_SKIPPED_RE.test(marked.output)) {
+			return {
+				culprit: null,
+				steps,
+				concluded: false,
+				reason: "only skipped commits are left to test — the result is undetermined",
+			};
+		}
+	}
+	return {
+		culprit: null,
+		steps,
+		concluded: false,
+		reason: `reached the ${deps.maxSteps}-step limit without converging`,
+	};
+}
+
+/**
+ * Run the predicate as `sh -c <run>` in `cwd` and return its exit code. A step
+ * that exceeds `timeoutMs` is killed and reported as a skip (125). Honors the
+ * outer abort signal by propagating a {@link ToolAbortError}.
+ */
+async function evaluatePredicate(
+	run: string,
+	cwd: string,
+	timeoutMs: number,
+	signal: AbortSignal | undefined,
+): Promise<number> {
+	const controller = new AbortController();
+	let timedOut = false;
+	const timer = setTimeout(() => {
+		timedOut = true;
+		controller.abort();
+	}, timeoutMs);
+	const onExternalAbort = () => controller.abort();
+	signal?.addEventListener("abort", onExternalAbort, { once: true });
+	try {
+		const child = Bun.spawn(["sh", "-c", run], {
+			cwd,
+			stdin: "ignore",
+			stdout: "ignore",
+			stderr: "ignore",
+			signal: controller.signal,
+		});
+		const exitCode = await child.exited;
+		if (timedOut) return SKIP_EXIT_CODE;
+		if (signal?.aborted) throw new ToolAbortError();
+		return exitCode ?? 1;
+	} catch (error) {
+		if (timedOut) return SKIP_EXIT_CODE;
+		if (signal?.aborted) throw new ToolAbortError();
+		throw new ToolError(`Failed to run bisect predicate: ${error instanceof Error ? error.message : String(error)}`);
+	} finally {
+		clearTimeout(timer);
+		signal?.removeEventListener("abort", onExternalAbort);
+	}
+}
+
+function formatSteps(steps: BisectStep[]): string {
+	if (steps.length === 0) return "  (seeded range converged immediately)";
+	return steps.map((step, index) => `  ${index + 1}. ${step.rev.slice(0, 12)} → ${step.verdict}`).join("\n");
+}
+
+/**
+ * Report the post-teardown worktree state honestly. `git bisect reset` plus a
+ * `git reset --hard` restores every *tracked* file to its pre-bisect state, so
+ * the common "predicate wrote to a tracked file" case is fully cleaned. A
+ * predicate that created *untracked* files is intentionally left untouched (the
+ * tool never deletes files it did not create), so those are surfaced as a note
+ * rather than hidden behind a false "restored" claim. Any residual tracked
+ * change is reported as a warning so the tool never overstates the cleanup.
+ */
+async function describeRestore(cwd: string): Promise<string> {
+	const tracked = (await git.status(cwd, { porcelainV1: true, untrackedFiles: "no" }).catch(() => "")).trim();
+	if (tracked) {
+		return `WARNING: working tree not fully restored — tracked changes remain after teardown:\n${tracked}`;
+	}
+	const all = (await git.status(cwd, { porcelainV1: true, untrackedFiles: "all" }).catch(() => "")).trim();
+	if (all) {
+		return "Working tree restored: tracked files reset to their pre-bisect state (untracked files the predicate created are left in place).";
+	}
+	return "Working tree restored to its pre-bisect state.";
+}
+
+export class BisectTool implements AgentTool<typeof bisectSchema, BisectToolDetails> {
+	readonly name = "bisect";
+	readonly label = "Bisect";
+	readonly summary = "Find the commit that introduced a regression by driving git bisect with a shell predicate";
+	readonly description: string;
+	readonly parameters = bisectSchema;
+	readonly strict = true;
+	readonly loadMode = "discoverable";
+	readonly intent = (args: Partial<BisectParams>): string =>
+		args.run ? `bisecting: ${args.run}` : "bisecting regression";
+
+	constructor(private readonly session: ToolSession) {
+		this.description = prompt.render(bisectDescription);
+	}
+
+	async execute(
+		_toolCallId: string,
+		params: BisectParams,
+		signal?: AbortSignal,
+		_onUpdate?: AgentToolUpdateCallback<BisectToolDetails>,
+		_context?: AgentToolContext,
+	): Promise<AgentToolResult<BisectToolDetails>> {
+		// Resolve the worktree top level once and run every git, predicate, and
+		// teardown operation from it — never from the raw session cwd. The session
+		// cwd may be a subdirectory that a candidate commit deletes mid-bisect
+		// (leaving later commands with a missing working directory), and `git
+		// bisect` itself must be run from the top level of the working tree.
+		const cwd = await git.repo.root(this.session.cwd, signal);
+		if (!cwd) {
+			throw new ToolError("bisect requires a git repository; the current directory is not inside a git worktree.");
+		}
+		const dirty = (await git.status(cwd, { porcelainV1: true, untrackedFiles: "no" })).trim();
+		if (dirty) {
+			throw new ToolError(
+				"Working tree has uncommitted changes. Commit or stash them before bisecting — git bisect checks out historical commits and would clobber uncommitted work.",
+			);
+		}
+
+		const goodSha = await git.ref.resolve(cwd, params.good, signal);
+		if (!goodSha) throw new ToolError(`Could not resolve the good ref: ${params.good}`);
+		const badSha = await git.ref.resolve(cwd, params.bad, signal);
+		if (!badSha) throw new ToolError(`Could not resolve the bad ref: ${params.bad}`);
+		if (goodSha === badSha) {
+			throw new ToolError("good and bad resolve to the same commit; there is nothing to bisect.");
+		}
+		if (!(await git.bisect.isAncestor(cwd, goodSha, badSha, signal))) {
+			throw new ToolError(
+				`good (${params.good}) must be an ancestor of bad (${params.bad}). Swap them or pick a correct known-good commit.`,
+			);
+		}
+
+		let outcome: BisectOutcome;
+		// Defensive reset in case a previous aborted bisect left state behind; a
+		// no-op when not bisecting (reset never throws).
+		await git.bisect.reset(cwd, signal);
+		try {
+			await git.bisect.start(cwd, signal);
+			const badMark = await git.bisect.bad(cwd, badSha, signal);
+			if (badMark.exitCode !== 0) {
+				throw new ToolError(`git bisect bad failed: ${badMark.stderr.trim() || badMark.stdout.trim()}`);
+			}
+			const goodMark = await git.bisect.good(cwd, goodSha, signal);
+			if (goodMark.exitCode !== 0) {
+				throw new ToolError(`git bisect good failed: ${goodMark.stderr.trim() || goodMark.stdout.trim()}`);
+			}
+			// A tiny good..bad range can converge on the seeding marks themselves.
+			const seededCulprit = parseFirstBadCommit(`${goodMark.stdout}\n${goodMark.stderr}`);
+			if (seededCulprit) {
+				outcome = { culprit: seededCulprit, steps: [], concluded: true };
+			} else {
+				outcome = await runBisectController(
+					{
+						maxSteps: params.maxSteps,
+						currentRev: async () => (await git.head.sha(cwd, signal)) ?? "HEAD",
+						evaluate: async () =>
+							classifyExit(
+								await evaluatePredicate(params.run, cwd, params.stepTimeoutMs, signal),
+								params.invert,
+							),
+						mark: async verdict => {
+							const result =
+								verdict === "good"
+									? await git.bisect.good(cwd, undefined, signal)
+									: verdict === "bad"
+										? await git.bisect.bad(cwd, undefined, signal)
+										: await git.bisect.skip(cwd, signal);
+							return { exitCode: result.exitCode, output: `${result.stdout}\n${result.stderr}` };
+						},
+					},
+					signal,
+				);
+			}
+		} finally {
+			// Always restore the working tree, even on error/abort. `git bisect
+			// reset` returns HEAD to the original branch/commit but leaves behind
+			// any tracked-file edits the `sh -c` predicate made mid-run. The tracked
+			// tree was verified clean before we started (precondition above), so
+			// discarding tracked modifications (reset --hard) only reverts the
+			// predicate's side effects, never user work; then bisect reset restores
+			// the original HEAD. Both are best-effort and must not throw here.
+			await git.reset(cwd, { hard: true }).catch(() => {});
+			await git.bisect.reset(cwd);
+		}
+
+		// Never claim a clean restore we did not actually achieve.
+		const restoreLine = await describeRestore(cwd);
+
+		if (outcome.concluded && outcome.culprit) {
+			const info = await git.bisect.describe(cwd, outcome.culprit).catch(() => null);
+			const lines = [
+				params.invert ? `First fixing commit: ${outcome.culprit}` : `First bad commit: ${outcome.culprit}`,
+			];
+			if (info) {
+				lines.push(`Author:  ${info.author}`, `Date:    ${info.date}`, `Subject: ${info.subject}`);
+				if (info.stat) lines.push("", "Files changed:", info.stat);
+			}
+			lines.push("", `Tested ${outcome.steps.length} revision(s):`, formatSteps(outcome.steps));
+			lines.push("", restoreLine);
+			return toolResult<BisectToolDetails>({
+				culprit: outcome.culprit,
+				invert: params.invert,
+				concluded: true,
+				steps: outcome.steps,
+				author: info?.author,
+				date: info?.date,
+				subject: info?.subject,
+			})
+				.text(lines.join("\n"))
+				.done();
+		}
+
+		const lines = [
+			`Bisect did not converge: ${outcome.reason ?? "unknown reason"}.`,
+			"",
+			`Tested ${outcome.steps.length} revision(s):`,
+			formatSteps(outcome.steps),
+			"",
+			restoreLine,
+		];
+		return toolResult<BisectToolDetails>({
+			culprit: null,
+			invert: params.invert,
+			concluded: false,
+			steps: outcome.steps,
+			reason: outcome.reason,
+		})
+			.text(lines.join("\n"))
+			.done();
+	}
+}