@sayknow-cli/coding-agent 0.3.6 → 0.3.8

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 { SKC_SESSION_ACTIVITY_FILE, sessionRoot } from "../skc-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(), "skc-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), SKC_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 "@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/ast-grep.ts

@@ -223,13 +223,16 @@ export class AstGrepTool implements AgentTool<typeof astGrepSchema, AstGrepToolD
 				const modelOut: string[] = [];
 				const displayOut: string[] = [];
 				const fileMatches = matchesByFile.get(relativePath) ?? [];
-				const lineNumberWidth = fileMatches.reduce((width, match) => {
-					const lineCount = match.text.split("\n").length;
-					const endLine = match.startLine + lineCount - 1;
-					return Math.max(width, String(match.startLine).length, String(endLine).length);
-				}, 0);
-				for (const match of fileMatches) {
-					const matchLines = match.text.split("\n");
+				const preparedMatches = fileMatches.map(match => {
+					const lines = match.text.split("\n");
+					const endLine = match.startLine + lines.length - 1;
+					return { match, lines, endLine };
+				});
+				const lineNumberWidth = preparedMatches.reduce(
+					(width, entry) => Math.max(width, String(entry.match.startLine).length, String(entry.endLine).length),
+					0,
+				);
+				for (const { match, lines: matchLines } of preparedMatches) {
 					for (let index = 0; index < matchLines.length; index++) {
 						const lineNumber = match.startLine + index;
 						const isMatch = index === 0;

package/src/tools/bash.ts

@@ -14,7 +14,10 @@ import bashDescription from "../prompts/tools/bash.md" with { type: "text" };
 import type { ClientBridgeTerminalExitStatus, ClientBridgeTerminalOutput } from "../session/client-bridge";
 import { DEFAULT_MAX_BYTES, streamTailUpdates, TailBuffer } from "../session/streaming-output";
 import { buildSkcRuntimeSessionEnv } from "../skc-runtime/goal-mode-request";
-import { SKC_RESTRICTED_ROLE_AGENT_BASH_ENV } from "../skc-runtime/restricted-role-agent-bash";
+import {
+	SKC_RALPLAN_ARTIFACT_ENV,
+	SKC_RESTRICTED_ROLE_AGENT_BASH_ENV,
+} from "../skc-runtime/restricted-role-agent-bash";
 import { renderStatusLine } from "../tui";
 import { CachedOutputBlock } from "../tui/output-block";
 import { getSixelLineMask } from "../utils/sixel";
@@ -530,13 +533,24 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 
 		const rawCommand = input.command;
 		const allowedPrefixes = this.session.bashAllowedPrefixes;
+		const isRestrictedRalplanArtifactEnv =
+			allowedPrefixes &&
+			allowedPrefixes.length > 0 &&
+			this.session.bashRestrictionProfile !== "read-only" &&
+			env &&
+			Object.keys(env).length === 1 &&
+			Object.hasOwn(env, SKC_RALPLAN_ARTIFACT_ENV) &&
+			rawCommand.includes(`--artifact-env ${SKC_RALPLAN_ARTIFACT_ENV}`);
 		if (
 			(this.session.bashRestrictionProfile === "read-only" || (allowedPrefixes && allowedPrefixes.length > 0)) &&
 			env &&
-			Object.keys(env).length > 0
+			Object.keys(env).length > 0 &&
+			!isRestrictedRalplanArtifactEnv
 		) {
 			const mode = this.session.bashRestrictionProfile === "read-only" ? "Read-only" : "Restricted role-agent";
-			throw new ToolError(`${mode} bash does not allow per-command env overrides.`);
+			throw new ToolError(
+				`${mode} bash only allows the ${SKC_RALPLAN_ARTIFACT_ENV} env override for --artifact-env.`,
+			);
 		}
 		if (allowedPrefixes && allowedPrefixes.length > 0) {
 			const commandsToCheck = rawCommand === command ? [command] : [rawCommand, command];
@@ -597,11 +611,13 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 					await Promise.all(
 						Object.entries(env).map(async ([key, value]) => [
 							key,
-							await expandInternalUrls(value, {
-								...internalUrlOptions,
-								ensureLocalParentDirs: true,
-								noEscape: true,
-							}),
+							key === SKC_RALPLAN_ARTIFACT_ENV
+								? value
+								: await expandInternalUrls(value, {
+										...internalUrlOptions,
+										ensureLocalParentDirs: true,
+										noEscape: true,
+									}),
 						]),
 					),
 				)
@@ -817,9 +833,22 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 			});
 		}
 
+		// Route through the client terminal when the client advertises the terminal capability.
+		// Skip when pty=true (PTY needs the local terminal UI).
+		const clientBridge =
+			this.session.bashRestrictionProfile === "read-only" ? undefined : this.session.getClientBridge?.();
+		const clientTerminalActive = Boolean(clientBridge?.capabilities.terminal && clientBridge.createTerminal && !pty);
+
 		const autoBgManager = AsyncJobManager.instance();
-		if (this.#autoBackgroundEnabled && !pty && autoBgManager) {
-			const autoBackgroundWaitMs = this.#resolveAutoBackgroundWaitMs(timeoutMs);
+		// Run non-PTY bash through the managed job path so Ctrl+B-twice fold-on-demand works
+		// even when auto-background is disabled. When a client terminal will handle the
+		// command, keep the existing bridge path unless auto-background is enabled.
+		if (!pty && autoBgManager && (this.#autoBackgroundEnabled || !clientTerminalActive)) {
+			// With auto-background off, wait past the command's own timeout so the job only
+			// leaves the foreground on an explicit Ctrl+B fold, never on an auto-background timer.
+			const autoBackgroundWaitMs = this.#autoBackgroundEnabled
+				? this.#resolveAutoBackgroundWaitMs(timeoutMs)
+				: timeoutMs + 1_000;
 			const startBackgrounded = autoBackgroundWaitMs === 0;
 			const job = this.#startManagedBashJob({
 				command,
@@ -875,10 +904,6 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 			});
 		}
 
-		// Route through the client terminal when the client advertises the terminal capability.
-		// Skip when pty=true (PTY needs the local terminal UI).
-		const clientBridge =
-			this.session.bashRestrictionProfile === "read-only" ? undefined : this.session.getClientBridge?.();
 		if (clientBridge?.capabilities.terminal && clientBridge.createTerminal && !pty) {
 			const handle = await clientBridge.createTerminal({
 				command,