neuvikon 0.2.8 → 0.2.10

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,133 @@ 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, since) {
+	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,
+			lastMessageId: since
+		};
+		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,
+			lastMessageId: since
+		};
+		let tokensIn = 0;
+		let tokensOut = 0;
+		let lastMessageId = since;
+		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;
+			if (usage.messageId !== void 0 && usage.messageId === lastMessageId) continue;
+			lastMessageId = usage.messageId ?? lastMessageId;
+			tokensIn += usage.tokensIn;
+			tokensOut += usage.tokensOut;
+		}
+		return {
+			tokensIn,
+			tokensOut,
+			offset: from + Buffer.byteLength(text.slice(0, lastNewline + 1)),
+			lastMessageId
+		};
+	} 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 id = message.id;
+	const fields = usage;
+	return {
+		messageId: typeof id === "string" && id ? id : void 0,
+		tokensIn: toCount$1(fields.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
@@ -239,8 +366,157 @@ function fail(message, hint) {
 	process.exit(1);
 }
 //#endregion
+//#region src/commands/report.ts
+/**
+* Agent hooks hand their context to the command on stdin as JSON. Reading the
+* transcript path from there means a hook is a bare `npx neuvikon report` with
+* nothing to wire up, and nothing to keep in sync when a tool renames a flag.
+*/
+async function transcriptFromHookPayload() {
+	const raw = await readStdin();
+	if (!raw.trim()) return void 0;
+	try {
+		const payload = JSON.parse(raw);
+		if (typeof payload !== "object" || payload === null) return void 0;
+		const path = payload.transcript_path;
+		return typeof path === "string" && path ? path : void 0;
+	} catch {
+		return;
+	}
+}
+function toCount(raw) {
+	if (raw === void 0) return void 0;
+	const value = Number(raw);
+	return Number.isFinite(value) && value >= 0 ? value : void 0;
+}
+/**
+* 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.
+*/
+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
+		});
+	}
+	if (baseline === void 0) return {
+		tokensIn: 0,
+		tokensOut: 0
+	};
+	const usage = readUsageSince(transcript, baseline, session.lastMessageId);
+	if (!usage) return {
+		tokensIn: 0,
+		tokensOut: 0
+	};
+	return {
+		tokensIn: usage.tokensIn,
+		tokensOut: usage.tokensOut,
+		nextOffset: usage.offset,
+		nextMessageId: usage.lastMessageId
+	};
+}
+/**
+* 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: delta.tokensIn,
+			tokensOut: delta.tokensOut
+		});
+	} catch {
+		return false;
+	}
+	if (delta.nextOffset !== void 0) writeSession({
+		...session,
+		transcriptOffset: delta.nextOffset,
+		lastMessageId: delta.nextMessageId
+	});
+	return true;
+}
+/**
+* Closes a session, carrying everything it accumulated since its last report.
+*
+* Switching tickets used to stop the outgoing session bare, which dropped every
+* token it had earned since its last turn ended — and a ticket that was started
+* and left inside a single turn recorded exactly nothing.
+*/
+async function stopSession(credentials, session, transcript) {
+	const usage = pendingUsage(session, transcript);
+	await post(credentials.url, "/api/agent/events", {
+		token: credentials.token,
+		event: "stop",
+		sessionKey: session.sessionKey,
+		tokensIn: usage.tokensIn,
+		tokensOut: usage.tokensOut
+	}).catch(() => 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.
+*/
+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,
+		nextMessageId: fromTranscript.nextMessageId
+	};
+	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/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,25 +526,25 @@ 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;
+		const transcript = transcriptPath ?? claudeTranscriptPath();
 		const result = await post(credentials.url, "/api/agent/events", {
 			token: credentials.token,
 			event: "start",
 			ticketRef: ref,
 			tool: "claude-code"
 		});
-		if (existing) await post(credentials.url, "/api/agent/events", {
-			token: credentials.token,
-			event: "stop",
-			sessionKey: existing.sessionKey
-		}).catch(() => void 0);
+		if (existing) await stopSession(credentials, existing, transcript);
+		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,175 +901,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
-* transcript path from there means a hook is a bare `npx neuvikon report` with
-* nothing to wire up, and nothing to keep in sync when a tool renames a flag.
-*/
-async function transcriptFromHookPayload() {
-	const raw = await readStdin();
-	if (!raw.trim()) return void 0;
-	try {
-		const payload = JSON.parse(raw);
-		if (typeof payload !== "object" || payload === null) return void 0;
-		const path = payload.transcript_path;
-		return typeof path === "string" && path ? path : void 0;
-	} catch {
-		return;
-	}
-}
-function toCount(raw) {
-	if (raw === void 0) return void 0;
-	const value = Number(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.
-*/
-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({
-			...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;
-	}
-	try {
-		await post(credentials.url, "/api/agent/events", {
-			token: credentials.token,
-			event: "report",
-			sessionKey: session.sessionKey,
-			tokensIn,
-			tokensOut
-		});
-	} catch {
-		return;
-	}
-	if (nextOffset !== void 0) writeSession({
-		...session,
-		transcriptOffset: nextOffset
-	});
-	if (flags.has("verbose")) info(dim(`Reported ${tokensIn ?? 0} in / ${tokensOut ?? 0} out`));
-}
-//#endregion
 //#region src/commands/start.ts
 const TOOLS = /* @__PURE__ */ new Set([
 	"claude-code",
@@ -812,17 +919,25 @@ 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) {
 		info(dim(`Already tracking ${ref}.`));
 		return;
 	}
+	const transcript = flags.get("transcript") || claudeTranscriptPath();
 	let result;
 	try {
 		result = await post(credentials.url, "/api/agent/events", {
@@ -839,15 +954,12 @@ async function start(flags, positional) {
 		}
 		throw error;
 	}
-	if (existing) await post(credentials.url, "/api/agent/events", {
-		token: credentials.token,
-		event: "stop",
-		sessionKey: existing.sessionKey
-	}).catch(() => void 0);
+	if (existing) await stopSession(credentials, existing, transcript);
 	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 +983,14 @@ 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) await stopSession(credentials, session, flags.get("transcript") || claudeTranscriptPath());
 	clearSession();
 	success(`Stopped tracking ${session.ticket}`);
 }
@@ -943,7 +1051,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.10",
   "description": "Tell Neuvikon which ticket your coding agent is working on.",
   "keywords": [
     "neuvikon",