neuvikon 0.2.6 → 0.2.8

package/README.md

@@ -74,7 +74,7 @@ being used, add the block above by hand.
 | | |
 |---|---|
 | `~/.neuvikon/config.json` | Token and deployment URL, `0600` |
-| `.neuvikon-session` | Which ticket this directory is tracking. Git-ignored by `init` |
+| `.neuvikon-session[.<id>]` | Which ticket this directory (or, under Claude Code, this agent) is tracking. Git-ignored by `init` |
 | `--dev` | Target the development deployment instead of production |
 | `NEUVIKON_URL` | Point at a self-hosted deployment. `--url` does the same per command |
 | `NEUVIKON_TOKEN` | Use this token instead of logging in — for CI and anywhere a browser cannot open |

package/dist/index.mjs

@@ -1,11 +1,284 @@
 #!/usr/bin/env node
 import { chmodSync, closeSync, existsSync, fstatSync, mkdirSync, openSync, readFileSync, readSync, rmSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
 import { homedir } from "node:os";
+import { dirname, join } from "node:path";
 import { spawn } from "node:child_process";
+//#region src/config.ts
+/**
+* The two deployments this CLI knows about. The browser origin is kept here
+* rather than read back from the server, because the API answers on a Convex
+* domain while approval happens on the web app's — one is not derivable from
+* the other, and guessing wrong sends people to a page that does not exist.
+*/
+const DEPLOYMENTS = {
+	production: {
+		api: "https://flexible-bird-801.eu-west-1.convex.site",
+		web: "https://www.neuvikon.space"
+	},
+	development: {
+		api: "https://calm-sturgeon-831.eu-west-1.convex.site",
+		web: "http://localhost:3000"
+	}
+};
+/**
+* `--dev` targets the development deployment; NEUVIKON_URL overrides the API
+* for a self-hosted install, in which case the web origin is unknowable and
+* falls back to the matching default.
+*/
+function resolveDeployment(flags) {
+	const base = flags.has("dev") ? DEPLOYMENTS.development : DEPLOYMENTS.production;
+	const override = flags.get("url") || process.env.NEUVIKON_URL;
+	return override ? {
+		api: override.trim().replace(/\/+$/, ""),
+		web: base.web
+	} : base;
+}
+const DEFAULT_SITE_URL = process.env.NEUVIKON_URL ?? DEPLOYMENTS.production.api;
+const CONFIG_DIR = join(homedir(), ".neuvikon");
+const CONFIG_PATH = join(CONFIG_DIR, "config.json");
+/**
+* Somewhere a browser cannot open — CI, a container, a remote box — there is no
+* way to complete a device login, so a token handed in through the environment
+* stands in for one. It wins over the config file: an explicit env var is the
+* more specific instruction.
+*/
+function credentialsFromEnv() {
+	const token = process.env.NEUVIKON_TOKEN;
+	if (!token) return null;
+	return {
+		token,
+		url: DEFAULT_SITE_URL
+	};
+}
+function readCredentials() {
+	const fromEnv = credentialsFromEnv();
+	if (fromEnv) return fromEnv;
+	let raw;
+	try {
+		raw = readFileSync(CONFIG_PATH, "utf8");
+	} catch {
+		return null;
+	}
+	try {
+		const parsed = JSON.parse(raw);
+		if (typeof parsed !== "object" || parsed === null) return null;
+		const { token, url } = parsed;
+		if (typeof token !== "string" || !token) return null;
+		if (typeof url !== "string" || !url) return null;
+		return parsed;
+	} catch {
+		return null;
+	}
+}
+/**
+* A token on disk is only as safe as its permissions, so directory and file are
+* locked to the owner on every write, not just on first create — an earlier
+* version may have left them readable.
+*/
+function writeCredentials(credentials) {
+	mkdirSync(CONFIG_DIR, {
+		recursive: true,
+		mode: 448
+	});
+	chmodSync(CONFIG_DIR, 448);
+	writeFileSync(CONFIG_PATH, `${JSON.stringify(credentials, null, 2)}\n`, { mode: 384 });
+	chmodSync(CONFIG_PATH, 384);
+}
+function clearCredentials() {
+	try {
+		rmSync(CONFIG_PATH);
+		return true;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region src/api.ts
+var ApiError = class extends Error {
+	status;
+	constructor(message, status) {
+		super(message);
+		this.status = status;
+		this.name = "ApiError";
+	}
+};
+/** A request that never reached the server: offline, DNS, TLS, timeout. */
+var NetworkError = class extends Error {
+	constructor(cause) {
+		super("Could not reach Neuvikon", { cause });
+		this.name = "NetworkError";
+	}
+};
+const TIMEOUT_MS = 15e3;
+/**
+* The one place an HTTP failure becomes a typed error. Callers decide what a
+* failure means — a hook wrapping the agent's turn wants to swallow it, `login`
+* wants to shout about it.
+*/
+async function post(url, path, body) {
+	let response;
+	try {
+		response = await fetch(`${url}${path}`, {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify(body),
+			signal: AbortSignal.timeout(TIMEOUT_MS)
+		});
+	} catch (error) {
+		throw new NetworkError(error);
+	}
+	const payload = await response.json().catch(() => ({}));
+	const error = typeof payload === "object" && payload !== null ? payload.error : void 0;
+	if (!response.ok) throw new ApiError(typeof error === "string" ? error : `Request failed with status ${response.status}`, response.status);
+	return payload;
+}
+function normalizeUrl(url) {
+	return url.trim().replace(/\/+$/, "");
+}
+//#endregion
+//#region src/session.ts
+/**
+* Distinguishes concurrent agents working in the *same* checkout — two Claude
+* Code panes both running `claude` in this directory get two session files,
+* because each one's process tree carries its own CLAUDE_CODE_SESSION_ID. A
+* tool that doesn't set it (or a person typing the command by hand) falls
+* back to the pre-multi-agent behavior of one session per directory.
+*/
+function instanceKey() {
+	return process.env.CLAUDE_CODE_SESSION_ID?.trim() || null;
+}
+/**
+* Scoped to the working directory rather than the machine: two checkouts driven
+* in parallel are two sessions, which is what running two agents means. Within
+* one checkout, `instanceKey()` further scopes it per agent so two panes in the
+* same directory don't stop each other's session out from under them.
+*/
+function sessionPath() {
+	const key = instanceKey();
+	const filename = key ? `.neuvikon-session.${key}` : ".neuvikon-session";
+	return join(process.cwd(), filename);
+}
+function readSession() {
+	let raw;
+	try {
+		raw = readFileSync(sessionPath(), "utf8");
+	} catch {
+		return null;
+	}
+	try {
+		const parsed = JSON.parse(raw);
+		if (typeof parsed !== "object" || parsed === null) return null;
+		const { sessionKey, ticket } = parsed;
+		if (typeof sessionKey !== "string" || typeof ticket !== "string") return null;
+		return parsed;
+	} catch {
+		return null;
+	}
+}
+function writeSession(session) {
+	writeFileSync(sessionPath(), `${JSON.stringify(session, null, 2)}\n`);
+}
+function clearSession() {
+	try {
+		rmSync(sessionPath());
+	} catch {}
+}
+//#endregion
+//#region src/ticket.ts
+/**
+* Ticket refs look like `AWKN-14`. This pattern is deliberately looser than the
+* server's — it pulls *candidates* out of arbitrary pasted prose and lets the
+* server decide which one is a real ticket in the caller's organization, so the
+* authoritative rule lives in exactly one place.
+*/
+const CANDIDATE = /\b([A-Z0-9]{2,8})-(\d{1,9})\b/g;
+/** Every distinct ref-shaped token in `text`, in the order it appears. */
+function extractTicketRefs(text) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const match of text.toUpperCase().matchAll(CANDIDATE)) {
+		if (/^\d+$/.test(match[1])) continue;
+		seen.add(`${match[1]}-${match[2]}`);
+	}
+	return [...seen];
+}
+/** Reads piped input, if any. Returns "" when stdin is a terminal. */
+async function readStdin() {
+	if (process.stdin.isTTY) return "";
+	const chunks = [];
+	for await (const chunk of process.stdin) chunks.push(chunk);
+	return Buffer.concat(chunks).toString("utf8");
+}
+//#endregion
+//#region src/ui.ts
+/**
+* Output helpers. Everything the agent shouldn't parse goes to stderr, so a
+* command's stdout stays a clean, pipeable value.
+*/
+const useColor = process.env.NO_COLOR === void 0 && process.stderr.isTTY === true;
+function paint(code, text) {
+	return useColor ? `\x1b[${code}m${text}\x1b[0m` : text;
+}
+const dim = (text) => paint("2", text);
+const bold = (text) => paint("1", text);
+const green = (text) => paint("32", text);
+const red = (text) => paint("31", text);
+const cyan = (text) => paint("36", text);
+function info(message) {
+	process.stderr.write(`${message}\n`);
+}
+function success(message) {
+	process.stderr.write(`${green("✓")} ${message}\n`);
+}
+function warn(message) {
+	process.stderr.write(`${red("!")} ${message}\n`);
+}
+/** Ends the process. Every user-facing failure funnels through here. */
+function fail(message, hint) {
+	process.stderr.write(`${red("✗")} ${message}\n`);
+	if (hint) process.stderr.write(`  ${dim(hint)}\n`);
+	process.exit(1);
+}
+//#endregion
+//#region src/commands/hook-start.ts
+/**
+* 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,
+* or a dead network are all just "nothing to do here", not errors.
+*/
+async function hookStart() {
+	try {
+		const credentials = readCredentials();
+		if (!credentials) return;
+		const [ref] = extractTicketRefs(await readStdin());
+		if (!ref) return;
+		const existing = readSession();
+		if (existing?.ticket === ref) return;
+		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);
+		writeSession({
+			sessionKey: result.sessionKey,
+			ticket: ref,
+			startedAt: Date.now()
+		});
+		success(`Tracking work on ${bold(ref)}`);
+	} catch {}
+}
+//#endregion
 //#region src/agents/hooks.ts
 const REPORT_COMMAND = "npx neuvikon report";
+const HEARTBEAT_COMMAND = "npx neuvikon report --heartbeat";
 const STOP_COMMAND = "npx neuvikon stop";
+const HOOK_START_COMMAND = "npx neuvikon hook-start";
 function hasCommand(groups, command) {
 	return (groups ?? []).some((group) => group.hooks.some((hook) => hook.command === command));
 }
@@ -21,8 +294,20 @@ function withCommand(groups, command) {
 * whose transcript exposes usage, per `usage.ts`. `Stop` fires after every
 * turn, exactly when `report` should read what the transcript gained since
 * last time; `SessionEnd` is the backstop for `stop` when nobody remembered
-* to run it by hand. Without this, `start`/`stop` are the only events an
-* agent ever sends and token usage never leaves zero.
+* to run it by hand.
+*
+* `UserPromptSubmit` covers `start`: relying on the agent to notice a ticket
+* ref in the prompt and remember to run `start` itself is exactly the failure
+* mode reported in NS-31 — an LLM that's mid-instruction-following skips it
+* often enough to be unreliable bookkeeping. The hook makes it deterministic
+* for Claude Code; other tools still fall back to the AGENTS.md instruction.
+*
+* `Notification` fires when Claude Code is blocked mid-turn — a permission
+* prompt, a question, waiting on the user — which is exactly when `Stop`
+* does *not* fire, since the turn hasn't finished. Without a heartbeat there
+* too, a session that's genuinely just waiting on a person reads as stale on
+* the board after `AGENT_SESSION_STALE_MS`, indistinguishable from one that
+* actually stopped (NS-32).
 */
 function installClaudeHooks(root) {
 	const relativePath = join(".claude", "settings.json");
@@ -39,7 +324,7 @@ function installClaudeHooks(root) {
 		};
 	}
 	const hooks = settings.hooks ?? {};
-	if (hasCommand(hooks.Stop, REPORT_COMMAND) && hasCommand(hooks.SessionEnd, STOP_COMMAND)) return {
+	if (hasCommand(hooks.Stop, REPORT_COMMAND) && hasCommand(hooks.Notification, HEARTBEAT_COMMAND) && hasCommand(hooks.SessionEnd, STOP_COMMAND) && hasCommand(hooks.UserPromptSubmit, HOOK_START_COMMAND)) return {
 		path: relativePath,
 		action: "unchanged"
 	};
@@ -48,7 +333,9 @@ function installClaudeHooks(root) {
 		hooks: {
 			...hooks,
 			Stop: withCommand(hooks.Stop, REPORT_COMMAND),
-			SessionEnd: withCommand(hooks.SessionEnd, STOP_COMMAND)
+			Notification: withCommand(hooks.Notification, HEARTBEAT_COMMAND),
+			SessionEnd: withCommand(hooks.SessionEnd, STOP_COMMAND),
+			UserPromptSubmit: withCommand(hooks.UserPromptSubmit, HOOK_START_COMMAND)
 		}
 	};
 	mkdirSync(dirname(path), { recursive: true });
@@ -156,17 +443,32 @@ function writeCursorRule(root) {
 		action: existing ? "updated" : "created"
 	};
 }
-/** Keeps the per-directory session file out of the user's commits. */
+/**
+* Keeps the per-directory session file(s) out of the user's commits. Globbed
+* because each concurrent agent gets its own `.neuvikon-session.<id>` file
+* now (see `session.ts`) — an exact-match `.neuvikon-session` line no longer
+* covers them, so an older, already-ignored project is migrated in place.
+*/
 function ignoreSessionFile(root) {
 	const path = join(root, ".gitignore");
 	if (!existsSync(join(root, ".git")) && !existsSync(path)) return null;
 	const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
-	if (existing.split("\n").some((line) => line.trim() === ".neuvikon-session")) return {
+	const lines = existing.split("\n");
+	if (lines.some((line) => line.trim() === ".neuvikon-session*")) return {
 		path: ".gitignore",
 		action: "unchanged"
 	};
+	const legacyIndex = lines.findIndex((line) => line.trim() === ".neuvikon-session");
+	if (legacyIndex !== -1) {
+		lines[legacyIndex] = ".neuvikon-session*";
+		writeFileSync(path, lines.join("\n"));
+		return {
+			path: ".gitignore",
+			action: "updated"
+		};
+	}
 	const prefix = existing.length === 0 ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
-	writeFileSync(path, `${existing}${prefix}# neuvikon CLI session state\n.neuvikon-session\n`);
+	writeFileSync(path, `${existing}${prefix}# neuvikon CLI session state\n.neuvikon-session*\n`);
 	return {
 		path: ".gitignore",
 		action: existing ? "updated" : "created"
@@ -197,126 +499,6 @@ function isInstalled(root) {
 	return false;
 }
 //#endregion
-//#region src/config.ts
-/**
-* The two deployments this CLI knows about. The browser origin is kept here
-* rather than read back from the server, because the API answers on a Convex
-* domain while approval happens on the web app's — one is not derivable from
-* the other, and guessing wrong sends people to a page that does not exist.
-*/
-const DEPLOYMENTS = {
-	production: {
-		api: "https://flexible-bird-801.eu-west-1.convex.site",
-		web: "https://www.neuvikon.space"
-	},
-	development: {
-		api: "https://calm-sturgeon-831.eu-west-1.convex.site",
-		web: "http://localhost:3000"
-	}
-};
-/**
-* `--dev` targets the development deployment; NEUVIKON_URL overrides the API
-* for a self-hosted install, in which case the web origin is unknowable and
-* falls back to the matching default.
-*/
-function resolveDeployment(flags) {
-	const base = flags.has("dev") ? DEPLOYMENTS.development : DEPLOYMENTS.production;
-	const override = flags.get("url") || process.env.NEUVIKON_URL;
-	return override ? {
-		api: override.trim().replace(/\/+$/, ""),
-		web: base.web
-	} : base;
-}
-const DEFAULT_SITE_URL = process.env.NEUVIKON_URL ?? DEPLOYMENTS.production.api;
-const CONFIG_DIR = join(homedir(), ".neuvikon");
-const CONFIG_PATH = join(CONFIG_DIR, "config.json");
-/**
-* Somewhere a browser cannot open — CI, a container, a remote box — there is no
-* way to complete a device login, so a token handed in through the environment
-* stands in for one. It wins over the config file: an explicit env var is the
-* more specific instruction.
-*/
-function credentialsFromEnv() {
-	const token = process.env.NEUVIKON_TOKEN;
-	if (!token) return null;
-	return {
-		token,
-		url: DEFAULT_SITE_URL
-	};
-}
-function readCredentials() {
-	const fromEnv = credentialsFromEnv();
-	if (fromEnv) return fromEnv;
-	let raw;
-	try {
-		raw = readFileSync(CONFIG_PATH, "utf8");
-	} catch {
-		return null;
-	}
-	try {
-		const parsed = JSON.parse(raw);
-		if (typeof parsed !== "object" || parsed === null) return null;
-		const { token, url } = parsed;
-		if (typeof token !== "string" || !token) return null;
-		if (typeof url !== "string" || !url) return null;
-		return parsed;
-	} catch {
-		return null;
-	}
-}
-/**
-* A token on disk is only as safe as its permissions, so directory and file are
-* locked to the owner on every write, not just on first create — an earlier
-* version may have left them readable.
-*/
-function writeCredentials(credentials) {
-	mkdirSync(CONFIG_DIR, {
-		recursive: true,
-		mode: 448
-	});
-	chmodSync(CONFIG_DIR, 448);
-	writeFileSync(CONFIG_PATH, `${JSON.stringify(credentials, null, 2)}\n`, { mode: 384 });
-	chmodSync(CONFIG_PATH, 384);
-}
-function clearCredentials() {
-	try {
-		rmSync(CONFIG_PATH);
-		return true;
-	} catch {
-		return false;
-	}
-}
-//#endregion
-//#region src/ui.ts
-/**
-* Output helpers. Everything the agent shouldn't parse goes to stderr, so a
-* command's stdout stays a clean, pipeable value.
-*/
-const useColor = process.env.NO_COLOR === void 0 && process.stderr.isTTY === true;
-function paint(code, text) {
-	return useColor ? `\x1b[${code}m${text}\x1b[0m` : text;
-}
-const dim = (text) => paint("2", text);
-const bold = (text) => paint("1", text);
-const green = (text) => paint("32", text);
-const red = (text) => paint("31", text);
-const cyan = (text) => paint("36", text);
-function info(message) {
-	process.stderr.write(`${message}\n`);
-}
-function success(message) {
-	process.stderr.write(`${green("✓")} ${message}\n`);
-}
-function warn(message) {
-	process.stderr.write(`${red("!")} ${message}\n`);
-}
-/** Ends the process. Every user-facing failure funnels through here. */
-function fail(message, hint) {
-	process.stderr.write(`${red("✗")} ${message}\n`);
-	if (hint) process.stderr.write(`  ${dim(hint)}\n`);
-	process.exit(1);
-}
-//#endregion
 //#region src/commands/init.ts
 /**
 * Separate from `login` because instructions are per-project and credentials
@@ -330,49 +512,6 @@ function init() {
 	if (!readCredentials()) warn("Not logged in yet — run `npx neuvikon login`.");
 }
 //#endregion
-//#region src/api.ts
-var ApiError = class extends Error {
-	status;
-	constructor(message, status) {
-		super(message);
-		this.status = status;
-		this.name = "ApiError";
-	}
-};
-/** A request that never reached the server: offline, DNS, TLS, timeout. */
-var NetworkError = class extends Error {
-	constructor(cause) {
-		super("Could not reach Neuvikon", { cause });
-		this.name = "NetworkError";
-	}
-};
-const TIMEOUT_MS = 15e3;
-/**
-* The one place an HTTP failure becomes a typed error. Callers decide what a
-* failure means — a hook wrapping the agent's turn wants to swallow it, `login`
-* wants to shout about it.
-*/
-async function post(url, path, body) {
-	let response;
-	try {
-		response = await fetch(`${url}${path}`, {
-			method: "POST",
-			headers: { "content-type": "application/json" },
-			body: JSON.stringify(body),
-			signal: AbortSignal.timeout(TIMEOUT_MS)
-		});
-	} catch (error) {
-		throw new NetworkError(error);
-	}
-	const payload = await response.json().catch(() => ({}));
-	const error = typeof payload === "object" && payload !== null ? payload.error : void 0;
-	if (!response.ok) throw new ApiError(typeof error === "string" ? error : `Request failed with status ${response.status}`, response.status);
-	return payload;
-}
-function normalizeUrl(url) {
-	return url.trim().replace(/\/+$/, "");
-}
-//#endregion
 //#region src/browser.ts
 /**
 * Best-effort. The URL is always printed too, so a headless box, an SSH session
@@ -450,40 +589,6 @@ async function login(flags) {
 	}
 }
 //#endregion
-//#region src/session.ts
-/**
-* Scoped to the working directory rather than the machine: two checkouts driven
-* in parallel are two sessions, which is what running two agents means.
-*/
-function sessionPath() {
-	return join(process.cwd(), ".neuvikon-session");
-}
-function readSession() {
-	let raw;
-	try {
-		raw = readFileSync(sessionPath(), "utf8");
-	} catch {
-		return null;
-	}
-	try {
-		const parsed = JSON.parse(raw);
-		if (typeof parsed !== "object" || parsed === null) return null;
-		const { sessionKey, ticket } = parsed;
-		if (typeof sessionKey !== "string" || typeof ticket !== "string") return null;
-		return parsed;
-	} catch {
-		return null;
-	}
-}
-function writeSession(session) {
-	writeFileSync(sessionPath(), `${JSON.stringify(session, null, 2)}\n`);
-}
-function clearSession() {
-	try {
-		rmSync(sessionPath());
-	} catch {}
-}
-//#endregion
 //#region src/commands/logout.ts
 /**
 * Deleting the local file is not enough: the token stays valid until the server
@@ -520,31 +625,6 @@ async function logout() {
 	info(dim("  Could not reach Neuvikon to revoke the token — revoke it in settings if it leaked."));
 }
 //#endregion
-//#region src/ticket.ts
-/**
-* Ticket refs look like `AWKN-14`. This pattern is deliberately looser than the
-* server's — it pulls *candidates* out of arbitrary pasted prose and lets the
-* server decide which one is a real ticket in the caller's organization, so the
-* authoritative rule lives in exactly one place.
-*/
-const CANDIDATE = /\b([A-Z0-9]{2,8})-(\d{1,9})\b/g;
-/** Every distinct ref-shaped token in `text`, in the order it appears. */
-function extractTicketRefs(text) {
-	const seen = /* @__PURE__ */ new Set();
-	for (const match of text.toUpperCase().matchAll(CANDIDATE)) {
-		if (/^\d+$/.test(match[1])) continue;
-		seen.add(`${match[1]}-${match[2]}`);
-	}
-	return [...seen];
-}
-/** Reads piped input, if any. Returns "" when stdin is a terminal. */
-async function readStdin() {
-	if (process.stdin.isTTY) return "";
-	const chunks = [];
-	for await (const chunk of process.stdin) chunks.push(chunk);
-	return Buffer.concat(chunks).toString("utf8");
-}
-//#endregion
 //#region src/usage.ts
 /**
 * Sums token usage out of a JSONL agent transcript, starting from `offset`.
@@ -861,6 +941,7 @@ async function main() {
 		case "logout": return logout();
 		case "init": return init();
 		case "start": return start(flags, positional);
+		case "hook-start": return hookStart();
 		case "report": return report(flags);
 		case "stop": return stop();
 		case "status": return status();

package/package.json

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