neuvikon 0.2.8 → 0.2.9

package/README.md

@@ -57,6 +57,9 @@ into `.claude/settings.json` for you, whenever that project already has one:
 {
   "hooks": {
     "Stop": [{ "hooks": [{ "type": "command", "command": "npx neuvikon report" }] }],
+    "Notification": [
+      { "hooks": [{ "type": "command", "command": "npx neuvikon report --heartbeat" }] }
+    ],
     "SessionEnd": [{ "hooks": [{ "type": "command", "command": "npx neuvikon stop" }] }]
   }
 }
@@ -66,6 +69,12 @@ into `.claude/settings.json` for you, whenever that project already has one:
 turn adds that turn rather than re-counting the conversation. It is silent and
 always exits 0 — a token count is never worth interrupting someone's work.
 
+`Notification` fires when Claude Code is blocked mid-turn — a permission
+prompt, a question, waiting on you — exactly when `Stop` doesn't fire yet. The
+`--heartbeat` flag tells `report` to still check in even when there's no new
+token usage to send, so a session that's genuinely just waiting on you doesn't
+read as stopped on the board.
+
 If `.claude/settings.json` doesn't exist yet, or another agent is the one
 being used, add the block above by hand.
 

package/dist/index.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { chmodSync, closeSync, existsSync, fstatSync, mkdirSync, openSync, readFileSync, readSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, closeSync, existsSync, fstatSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { spawn } from "node:child_process";
@@ -209,6 +209,125 @@ async function readStdin() {
 	return Buffer.concat(chunks).toString("utf8");
 }
 //#endregion
+//#region src/usage.ts
+/**
+* Sums token usage out of a JSONL agent transcript, starting from `offset`.
+*
+* Reading incrementally is what makes a per-turn hook safe to call repeatedly:
+* each call reports only what was appended since the last one. Anything that
+* doesn't parse is skipped rather than fatal — a transcript being appended to
+* while we read it will have a torn final line, and that is normal, not an
+* error worth failing a user's turn over.
+*/
+/**
+* Where the transcript currently ends, so a session that starts mid-conversation
+* can mark its starting point instead of counting what came before it.
+*/
+function transcriptSize(path) {
+	let fd;
+	try {
+		fd = openSync(path, "r");
+	} catch {
+		return null;
+	}
+	try {
+		return fstatSync(fd).size;
+	} catch {
+		return null;
+	} finally {
+		closeSync(fd);
+	}
+}
+function readUsageSince(path, offset) {
+	let fd;
+	try {
+		fd = openSync(path, "r");
+	} catch {
+		return null;
+	}
+	try {
+		const size = fstatSync(fd).size;
+		const from = offset > size ? 0 : offset;
+		if (size === from) return {
+			tokensIn: 0,
+			tokensOut: 0,
+			offset: size
+		};
+		const buffer = Buffer.alloc(size - from);
+		readSync(fd, buffer, 0, buffer.length, from);
+		const text = buffer.toString("utf8");
+		const lastNewline = text.lastIndexOf("\n");
+		if (lastNewline === -1) return {
+			tokensIn: 0,
+			tokensOut: 0,
+			offset: from
+		};
+		let tokensIn = 0;
+		let tokensOut = 0;
+		for (const line of text.slice(0, lastNewline).split("\n")) {
+			if (!line.trim()) continue;
+			let row;
+			try {
+				row = JSON.parse(line);
+			} catch {
+				continue;
+			}
+			const usage = extractUsage(row);
+			if (!usage) continue;
+			tokensIn += usage.tokensIn;
+			tokensOut += usage.tokensOut;
+		}
+		return {
+			tokensIn,
+			tokensOut,
+			offset: from + Buffer.byteLength(text.slice(0, lastNewline + 1))
+		};
+	} catch {
+		return null;
+	} finally {
+		closeSync(fd);
+	}
+}
+function toCount$1(value) {
+	return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+}
+function extractUsage(row) {
+	if (typeof row !== "object" || row === null) return null;
+	const message = row.message;
+	if (typeof message !== "object" || message === null) return null;
+	const usage = message.usage;
+	if (typeof usage !== "object" || usage === null) return null;
+	const fields = usage;
+	return {
+		tokensIn: toCount$1(fields.input_tokens) + toCount$1(fields.cache_read_input_tokens) + toCount$1(fields.cache_creation_input_tokens),
+		tokensOut: toCount$1(fields.output_tokens)
+	};
+}
+/**
+* Claude Code's transcript for the session this command was spawned from.
+*
+* Hooks are handed a `transcript_path` on stdin, but `start` and `stop` are run
+* by the agent's own shell, which only gets the session id in the environment.
+* That id is a uuid, so finding the file by name is exact — and doesn't depend
+* on how Claude Code derives a project directory name from the working
+* directory, which is not a documented format.
+*/
+function claudeTranscriptPath() {
+	const sessionId = process.env.CLAUDE_CODE_SESSION_ID?.trim();
+	if (!sessionId) return void 0;
+	const projects = join(homedir(), ".claude", "projects");
+	let directories;
+	try {
+		directories = readdirSync(projects);
+	} catch {
+		return;
+	}
+	for (const directory of directories) {
+		const candidate = join(projects, directory, `${sessionId}.jsonl`);
+		if (existsSync(candidate)) return candidate;
+	}
+}
+//#endregion
 //#region src/ui.ts
 /**
 * Output helpers. Everything the agent shouldn't parse goes to stderr, so a
@@ -241,6 +360,28 @@ function fail(message, hint) {
 //#endregion
 //#region src/commands/hook-start.ts
 /**
+* `UserPromptSubmit` fires before the turn runs, which is what lets it capture
+* a token baseline at the transcript's current size — anything read from that
+* offset onward is this ticket's usage. Reading it here, instead of lazily on
+* the first `Stop`, is what `report.ts` used to do: by the time `Stop` fires
+* the first turn's usage is already appended, so that baseline came too late
+* and silently discarded a whole turn's tokens (NS-33).
+*/
+function parsePayload(raw) {
+	if (!raw.trim()) return {};
+	try {
+		const payload = JSON.parse(raw);
+		if (typeof payload !== "object" || payload === null) return {};
+		const record = payload;
+		return {
+			prompt: typeof record.prompt === "string" ? record.prompt : void 0,
+			transcriptPath: typeof record.transcript_path === "string" ? record.transcript_path : void 0
+		};
+	} catch {
+		return {};
+	}
+}
+/**
 * The `UserPromptSubmit` counterpart to `start`. Unlike `start`, this runs on
 * *every* prompt regardless of whether it mentions a ticket, so it must never
 * fail the hook and block the user's message — no credentials, no ticket ref,
@@ -250,7 +391,8 @@ async function hookStart() {
 	try {
 		const credentials = readCredentials();
 		if (!credentials) return;
-		const [ref] = extractTicketRefs(await readStdin());
+		const { prompt, transcriptPath } = parsePayload(await readStdin());
+		const [ref] = extractTicketRefs(prompt ?? "");
 		if (!ref) return;
 		const existing = readSession();
 		if (existing?.ticket === ref) return;
@@ -265,10 +407,13 @@ async function hookStart() {
 			event: "stop",
 			sessionKey: existing.sessionKey
 		}).catch(() => void 0);
+		const transcript = transcriptPath ?? claudeTranscriptPath();
+		const transcriptOffset = transcript ? transcriptSize(transcript) ?? void 0 : void 0;
 		writeSession({
 			sessionKey: result.sessionKey,
 			ticket: ref,
-			startedAt: Date.now()
+			startedAt: Date.now(),
+			transcriptOffset
 		});
 		success(`Tracking work on ${bold(ref)}`);
 	} catch {}
@@ -625,101 +770,6 @@ async function logout() {
 	info(dim("  Could not reach Neuvikon to revoke the token — revoke it in settings if it leaked."));
 }
 //#endregion
-//#region src/usage.ts
-/**
-* Sums token usage out of a JSONL agent transcript, starting from `offset`.
-*
-* Reading incrementally is what makes a per-turn hook safe to call repeatedly:
-* each call reports only what was appended since the last one. Anything that
-* doesn't parse is skipped rather than fatal — a transcript being appended to
-* while we read it will have a torn final line, and that is normal, not an
-* error worth failing a user's turn over.
-*/
-/**
-* Where the transcript currently ends, so a session that starts mid-conversation
-* can mark its starting point instead of counting what came before it.
-*/
-function transcriptSize(path) {
-	let fd;
-	try {
-		fd = openSync(path, "r");
-	} catch {
-		return null;
-	}
-	try {
-		return fstatSync(fd).size;
-	} catch {
-		return null;
-	} finally {
-		closeSync(fd);
-	}
-}
-function readUsageSince(path, offset) {
-	let fd;
-	try {
-		fd = openSync(path, "r");
-	} catch {
-		return null;
-	}
-	try {
-		const size = fstatSync(fd).size;
-		const from = offset > size ? 0 : offset;
-		if (size === from) return {
-			tokensIn: 0,
-			tokensOut: 0,
-			offset: size
-		};
-		const buffer = Buffer.alloc(size - from);
-		readSync(fd, buffer, 0, buffer.length, from);
-		const text = buffer.toString("utf8");
-		const lastNewline = text.lastIndexOf("\n");
-		if (lastNewline === -1) return {
-			tokensIn: 0,
-			tokensOut: 0,
-			offset: from
-		};
-		let tokensIn = 0;
-		let tokensOut = 0;
-		for (const line of text.slice(0, lastNewline).split("\n")) {
-			if (!line.trim()) continue;
-			let row;
-			try {
-				row = JSON.parse(line);
-			} catch {
-				continue;
-			}
-			const usage = extractUsage(row);
-			if (!usage) continue;
-			tokensIn += usage.tokensIn;
-			tokensOut += usage.tokensOut;
-		}
-		return {
-			tokensIn,
-			tokensOut,
-			offset: from + Buffer.byteLength(text.slice(0, lastNewline + 1))
-		};
-	} catch {
-		return null;
-	} finally {
-		closeSync(fd);
-	}
-}
-function toCount$1(value) {
-	return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
-}
-function extractUsage(row) {
-	if (typeof row !== "object" || row === null) return null;
-	const message = row.message;
-	if (typeof message !== "object" || message === null) return null;
-	const usage = message.usage;
-	if (typeof usage !== "object" || usage === null) return null;
-	const fields = usage;
-	return {
-		tokensIn: toCount$1(fields.input_tokens) + toCount$1(fields.cache_read_input_tokens) + toCount$1(fields.cache_creation_input_tokens),
-		tokensOut: toCount$1(fields.output_tokens)
-	};
-}
-//#endregion
 //#region src/commands/report.ts
 /**
 * Agent hooks hand their context to the command on stdin as JSON. Reading the
@@ -744,54 +794,87 @@ function toCount(raw) {
 	return Number.isFinite(value) && value >= 0 ? value : void 0;
 }
 /**
-* Called from an agent hook on every turn, so it is deliberately silent and
-* never exits non-zero: a token count is not worth interrupting someone's work
-* over, and a hook that fails loudly is a hook people uninstall.
+* What the transcript has accumulated since this session's baseline.
+*
+* A session with no baseline yet establishes one here rather than counting
+* from the top: everything before the ticket started belongs to whatever the
+* agent was doing beforehand, not to this ticket.
 */
-async function report(flags) {
-	const credentials = readCredentials();
-	const session = readSession();
-	if (!credentials || !session) {
-		if (flags.has("verbose")) info(dim(credentials ? "No ticket is being tracked here." : "Not logged in."));
-		return;
-	}
-	let tokensIn = toCount(flags.get("tokens-in"));
-	let tokensOut = toCount(flags.get("tokens-out"));
-	let nextOffset;
-	const transcript = flags.get("transcript") || await transcriptFromHookPayload();
-	if (transcript) {
-		const baseline = session.transcriptOffset ?? transcriptSize(transcript);
-		if (session.transcriptOffset === void 0 && baseline !== null) writeSession({
+function pendingUsage(session, transcript) {
+	if (!transcript) return {
+		tokensIn: 0,
+		tokensOut: 0
+	};
+	let baseline = session.transcriptOffset;
+	if (baseline === void 0) {
+		baseline = transcriptSize(transcript) ?? void 0;
+		if (baseline !== void 0) writeSession({
 			...session,
 			transcriptOffset: baseline
 		});
-		const usage = baseline === null ? null : readUsageSince(transcript, baseline);
-		if (usage) {
-			tokensIn = (tokensIn ?? 0) + usage.tokensIn;
-			tokensOut = (tokensOut ?? 0) + usage.tokensOut;
-			nextOffset = usage.offset;
-		}
-	}
-	if (!tokensIn && !tokensOut) {
-		if (flags.has("verbose")) info(dim("No new usage to report."));
-		return;
 	}
+	if (baseline === void 0) return {
+		tokensIn: 0,
+		tokensOut: 0
+	};
+	const usage = readUsageSince(transcript, baseline);
+	if (!usage) return {
+		tokensIn: 0,
+		tokensOut: 0
+	};
+	return {
+		tokensIn: usage.tokensIn,
+		tokensOut: usage.tokensOut,
+		nextOffset: usage.offset
+	};
+}
+/**
+* Hands a delta to the server, advancing the local offset only once it is
+* accepted — a dropped request leaves the window to be retried by the next
+* call instead of silently losing those tokens.
+*/
+async function postUsage(credentials, session, delta) {
 	try {
 		await post(credentials.url, "/api/agent/events", {
 			token: credentials.token,
 			event: "report",
 			sessionKey: session.sessionKey,
-			tokensIn,
-			tokensOut
+			tokensIn: delta.tokensIn,
+			tokensOut: delta.tokensOut
 		});
 	} catch {
-		return;
+		return false;
 	}
-	if (nextOffset !== void 0) writeSession({
+	if (delta.nextOffset !== void 0) writeSession({
 		...session,
-		transcriptOffset: nextOffset
+		transcriptOffset: delta.nextOffset
 	});
-	if (flags.has("verbose")) info(dim(`Reported ${tokensIn ?? 0} in / ${tokensOut ?? 0} out`));
+	return true;
+}
+/**
+* Called from an agent hook on every turn, so it is deliberately silent and
+* never exits non-zero: a token count is not worth interrupting someone's work
+* over, and a hook that fails loudly is a hook people uninstall.
+*/
+async function report(flags) {
+	const credentials = readCredentials();
+	const session = readSession();
+	if (!credentials || !session) {
+		if (flags.has("verbose")) info(dim(credentials ? "No ticket is being tracked here." : "Not logged in."));
+		return;
+	}
+	const fromTranscript = pendingUsage(session, flags.get("transcript") || await transcriptFromHookPayload() || claudeTranscriptPath());
+	const delta = {
+		tokensIn: (toCount(flags.get("tokens-in")) ?? 0) + fromTranscript.tokensIn,
+		tokensOut: (toCount(flags.get("tokens-out")) ?? 0) + fromTranscript.tokensOut,
+		nextOffset: fromTranscript.nextOffset
+	};
+	if (!delta.tokensIn && !delta.tokensOut && !flags.has("heartbeat")) {
+		if (flags.has("verbose")) info(dim("No new usage to report."));
+		return;
+	}
+	await postUsage(credentials, session, delta);
+	if (flags.has("verbose")) info(dim(`Reported ${delta.tokensIn} in / ${delta.tokensOut} out`));
 }
 //#endregion
 //#region src/commands/start.ts
@@ -812,11 +895,18 @@ async function resolveRef(flags, positional) {
 	if (refs.length === 0) fail("No ticket reference found.", "Pass one with --ticket EWWQ-1, or pipe the ticket text in.");
 	return refs[0];
 }
+/**
+* An agent shelling out to `start` rarely passes `--tool`, and "other" is a
+* worse answer than the one the environment already gives us.
+*/
+function detectTool() {
+	return process.env.CLAUDE_CODE_SESSION_ID ? "claude-code" : "other";
+}
 async function start(flags, positional) {
 	const credentials = readCredentials();
 	if (!credentials) fail("Not logged in.", "Run `npx neuvikon login` first.");
 	const ref = await resolveRef(flags, positional);
-	const tool = flags.get("tool") ?? "other";
+	const tool = flags.get("tool") ?? detectTool();
 	if (!TOOLS.has(tool)) fail(`Unknown tool "${tool}".`, `Expected one of: ${[...TOOLS].join(", ")}.`);
 	const existing = readSession();
 	if (existing?.ticket === ref) {
@@ -844,10 +934,12 @@ async function start(flags, positional) {
 		event: "stop",
 		sessionKey: existing.sessionKey
 	}).catch(() => void 0);
+	const transcript = flags.get("transcript") || claudeTranscriptPath();
 	writeSession({
 		sessionKey: result.sessionKey,
 		ticket: ref,
-		startedAt: Date.now()
+		startedAt: Date.now(),
+		transcriptOffset: transcript ? transcriptSize(transcript) ?? void 0 : void 0
 	});
 	success(`Tracking work on ${bold(ref)}`);
 }
@@ -871,18 +963,23 @@ function status() {
 }
 //#endregion
 //#region src/commands/stop.ts
-async function stop() {
+async function stop(flags) {
 	const session = readSession();
 	if (!session) {
 		info(dim("No ticket is being tracked here."));
 		return;
 	}
 	const credentials = readCredentials();
-	if (credentials) await post(credentials.url, "/api/agent/events", {
-		token: credentials.token,
-		event: "stop",
-		sessionKey: session.sessionKey
-	}).catch(() => void 0);
+	if (credentials) {
+		const usage = pendingUsage(session, flags.get("transcript") || claudeTranscriptPath());
+		await post(credentials.url, "/api/agent/events", {
+			token: credentials.token,
+			event: "stop",
+			sessionKey: session.sessionKey,
+			tokensIn: usage.tokensIn,
+			tokensOut: usage.tokensOut
+		}).catch(() => void 0);
+	}
 	clearSession();
 	success(`Stopped tracking ${session.ticket}`);
 }
@@ -943,7 +1040,7 @@ async function main() {
 		case "start": return start(flags, positional);
 		case "hook-start": return hookStart();
 		case "report": return report(flags);
-		case "stop": return stop();
+		case "stop": return stop(flags);
 		case "status": return status();
 		case void 0:
 		case "help":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neuvikon",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "description": "Tell Neuvikon which ticket your coding agent is working on.",
   "keywords": [
     "neuvikon",