@v1nvn/agentic-core 0.25.0 → 0.26.0

package/README.md

@@ -1,9 +1,9 @@
 # @v1nvn/agentic-core
 
-The shared runtime of the `@v1nvn` agent tools: the last-reply transcript
-reader and the fixed-width text formatting every tool CLI prints through.
-A library — no bin, not directly runnable; `zai`, `tokens`, `rm`, `md`, and
-`statusline` consume it as a workspace dependency.
+The shared runtime of the `@v1nvn` agent tools: transcript reading, CLI and
+hook plumbing, report formatting, logging, and the MCP server lifecycle
+helpers. A library — no bin, not directly runnable; every other package
+consumes it as a workspace dependency.
 
 User-facing docs: [root README](../../README.md).
 
@@ -12,9 +12,13 @@ User-facing docs: [root README](../../README.md).
 | File | Role |
 |---|---|
 | `src/last-reply.ts` | finds the previous assistant reply across local Claude Code transcripts |
-| `src/text-format.ts` | fixed-width tables and text the terminals render identically |
-| `src/cli.ts` | usage/exit helpers shared by the tool bins |
+| `src/input.ts` | stdin and markdown-file input with the CLI error contracts |
+| `src/text-format.ts` | fixed-width tables, rules, bars, and date/pad helpers the terminals render identically |
+| `src/cli.ts` | quiet commander parsing and usage/exit helpers shared by the tool bins |
 | `src/hook.ts` | the `UserPromptExpansion` hook plumbing the zero-token plugins ride |
+| `src/logger.ts` | level-filtered stderr logger for the MCP servers |
+| `src/shutdown.ts` | close-then-exit signal handling for the server entrypoints |
+| `src/dev.ts` | the hot-reload watcher wiring the servers' `yarn dev` harnesses share |
 | `src/index.ts` | the public entry — re-exports the modules above |
 
 ## Develop
@@ -30,3 +34,5 @@ yarn lint && yarn typecheck       # from the repo root
 - No tool-specific logic lives here — a concern lands in core only when two
   or more tools need it.
 - `last-reply` reads transcripts only; it never writes.
+- The logger and shutdown/dev helpers write to stderr only — stdout carries
+  the MCP transport on the servers.

package/dist/index.js

@@ -1,40 +1,53 @@
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-//#region src/hook.ts
-/**
-* Read the Claude Code hook event JSON from stdin; empty or unparseable input
-* yields an empty event, never a thrown error — a hook must always answer.
-*/
-function readHookEvent(stream = process.stdin) {
-	return new Promise((resolve) => {
+//#region src/input.ts
+function readAll(stream) {
+	return new Promise((resolve, reject) => {
 		let data = "";
 		stream.setEncoding("utf8");
 		stream.on("data", (chunk) => {
 			data += chunk;
 		});
 		stream.on("end", () => {
-			try {
-				resolve(JSON.parse(data));
-			} catch {
-				resolve({});
-			}
-		});
-		stream.on("error", () => {
-			resolve({});
+			resolve(data);
 		});
+		stream.on("error", reject);
 	});
 }
+function readStdin(stream = process.stdin) {
+	return readAll(stream);
+}
+/** A markdown file's contents, with the CLI's no-such-file error. */
+function readMarkdownFile(path) {
+	if (!statSync(path, { throwIfNoEntry: false })?.isFile()) throw new Error(`no such file: ${path}`);
+	return readFileSync(path, "utf8");
+}
+//#endregion
+//#region src/hook.ts
+/**
+* Read the Claude Code hook event JSON from stdin; empty or unparseable input
+* yields an empty event, never a thrown error — a hook must always answer.
+*/
+function readHookEvent(stream = process.stdin) {
+	return readAll(stream).then((data) => {
+		try {
+			return JSON.parse(data);
+		} catch {
+			return {};
+		}
+	}, () => ({}));
+}
 /**
 * Which transcript lastReply should read, per the hook event: transcript_path
 * when it names a real file, else session_id, else nothing (lastReply then
 * falls back to the newest session for the current project).
 */
 function replyTarget(event) {
-	if (event.transcript_path !== void 0 && isFile$1(event.transcript_path)) return event.transcript_path;
+	if (event.transcript_path !== void 0 && isFile(event.transcript_path)) return event.transcript_path;
 	return event.session_id || void 0;
 }
-function isFile$1(path) {
+function isFile(path) {
 	try {
 		return statSync(path).isFile();
 	} catch {
@@ -53,15 +66,15 @@ function emitHookBlock(reason) {
 }
 //#endregion
 //#region src/cli.ts
-function parseQuietly(program, args) {
+function parseQuietly(program, args, recover) {
 	try {
 		program.allowExcessArguments(false).exitOverride().configureOutput({
 			writeOut: () => void 0,
 			writeErr: () => void 0
 		}).parse([...args], { from: "user" });
 		return program;
-	} catch {
-		return;
+	} catch (err) {
+		return recover?.(err);
 	}
 }
 function printUsageAndExit(program) {
@@ -87,20 +100,45 @@ async function hookOrPrint(hook, failure, run, stdin = process.stdin) {
 	}
 }
 //#endregion
-//#region src/last-reply.ts
-function isFile(path) {
-	try {
-		return statSync(path).isFile();
-	} catch {
-		return false;
-	}
+//#region src/dev.ts
+var RELOAD_DEBOUNCE_MS = 150;
+var IGNORED_SEGMENTS = [
+	"/node_modules/",
+	"/dist/",
+	"/.git/",
+	"/coverage/"
+];
+function shouldReload(file) {
+	return IGNORED_SEGMENTS.every((seg) => !file.includes(seg));
+}
+/**
+* Debounced file-change reloads, serialized via a promise chain: concurrent
+* saves never overlap, and a mid-reload save still produces a follow-up.
+*/
+function watchWithReload(vite, reload) {
+	let chain = Promise.resolve();
+	let timer;
+	vite.watcher.on("change", (file) => {
+		if (!shouldReload(file)) return;
+		if (timer) clearTimeout(timer);
+		timer = setTimeout(() => {
+			timer = void 0;
+			chain = chain.then(reload);
+		}, RELOAD_DEBOUNCE_MS);
+	});
 }
+//#endregion
+//#region src/last-reply.ts
 function textBlocks(entry) {
 	const content = entry.message?.content;
 	if (entry.type !== "assistant" || !Array.isArray(content)) return;
 	const blocks = content.filter((b) => typeof b === "object" && b !== null && b.type === "text");
 	return blocks.length > 0 ? blocks : void 0;
 }
+function claudeProjectsDir() {
+	const claudeDir = process.env.CLAUDE_DIR ?? join(homedir(), ".claude");
+	return join(claudeDir, "projects");
+}
 /**
 * The last assistant text reply from a Claude Code session, reproducing Claude
 * Code's `/copy` byte-for-byte: the last assistant entry that contains a
@@ -111,9 +149,8 @@ function textBlocks(entry) {
 *   nothing to use the newest session for the current project.
 */
 function lastReply(arg) {
-	const claudeDir = process.env.CLAUDE_DIR ?? join(homedir(), ".claude");
 	const proj = (process.env.CLAUDE_PROJECT_DIR ?? process.cwd()).replaceAll("/", "-");
-	const projDir = join(claudeDir, "projects", proj);
+	const projDir = join(claudeProjectsDir(), proj);
 	let file;
 	if (arg !== void 0) file = isFile(arg) ? arg : join(projDir, `${arg}.jsonl`);
 	else if (existsSync(projDir)) {
@@ -139,6 +176,62 @@ function lastReply(arg) {
 	return (last ?? []).map((b) => b.text ?? "").join("\n\n");
 }
 //#endregion
+//#region src/logger.ts
+var LEVEL_RANK = {
+	debug: 10,
+	info: 20,
+	warn: 30,
+	error: 40,
+	silent: Number.MAX_SAFE_INTEGER
+};
+function levelEnabled(active, wanted) {
+	return LEVEL_RANK[wanted] >= LEVEL_RANK[active];
+}
+var LEVEL_LABEL = {
+	debug: "DEBUG",
+	error: "ERROR",
+	info: "INFO",
+	warn: "WARN"
+};
+var Logger = class {
+	activeLevel;
+	stderr;
+	constructor(activeLevel, stderr = (line) => process.stderr.write(`${line}\n`)) {
+		this.activeLevel = activeLevel;
+		this.stderr = stderr;
+	}
+	debug(message) {
+		this.log("debug", message);
+	}
+	error(message) {
+		this.log("error", message);
+	}
+	info(message) {
+		this.log("info", message);
+	}
+	warn(message) {
+		this.log("warn", message);
+	}
+	log(level, message) {
+		if (levelEnabled(this.activeLevel, level)) this.stderr(`${LEVEL_LABEL[level]} ${message}`);
+	}
+};
+//#endregion
+//#region src/shutdown.ts
+/** Close each closable in order (best-effort), then force-exit. */
+function shutdownOnSignals(closables, signals = ["SIGINT", "SIGTERM"]) {
+	const shutdown = () => {
+		closables.reduce((acc, closable) => acc.then(async () => {
+			try {
+				await closable.close();
+			} catch {}
+		}), Promise.resolve()).finally(() => {
+			process.exit(0);
+		});
+	};
+	for (const signal of signals) process.on(signal, shutdown);
+}
+//#endregion
 //#region src/text-format.ts
 /**
 * Plain-text rendering primitives shared by the zai and tokens report
@@ -170,6 +263,17 @@ var EIGHTHS = [
 	"▊",
 	"▉"
 ];
+var RULE_WIDTH = 68;
+function rule() {
+	return "─".repeat(68);
+}
+function pad2(n) {
+	return String(n).padStart(2, "0");
+}
+/** Local-time `YYYY-MM-DD` key. */
+function ymd(date) {
+	return `${date.getFullYear()}-${pad2(date.getMonth() + 1)}-${pad2(date.getDate())}`;
+}
 function fmtTokens(n) {
 	if (n == null || Number.isNaN(n)) return "—";
 	if (n >= 1e9) return (n / 1e9).toFixed(1) + "B";
@@ -209,6 +313,6 @@ function meter(pct, width) {
 	return "█".repeat(filled) + "░".repeat(width - filled);
 }
 //#endregion
-export { MONTHS, barField, emitHookBlock, fmtNum, fmtTokens, hookOrPrint, lastReply, meter, padL, padR, parseQuietly, printUsageAndExit, readHookEvent, replyTarget };
+export { Logger, MONTHS, RULE_WIDTH, barField, claudeProjectsDir, emitHookBlock, fmtNum, fmtTokens, hookOrPrint, isFile, lastReply, levelEnabled, meter, pad2, padL, padR, parseQuietly, printUsageAndExit, readAll, readHookEvent, readMarkdownFile, readStdin, replyTarget, rule, shutdownOnSignals, watchWithReload, ymd };
 
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/hook.ts","../src/cli.ts","../src/last-reply.ts","../src/text-format.ts"],"sourcesContent":["import { statSync } from 'node:fs';\n\nexport interface HookEvent {\n  cwd?: string;\n  session_id?: string;\n  transcript_path?: string;\n}\n\n/**\n * Read the Claude Code hook event JSON from stdin; empty or unparseable input\n * yields an empty event, never a thrown error — a hook must always answer.\n */\nexport function readHookEvent(\n  stream: NodeJS.ReadableStream = process.stdin,\n): Promise<HookEvent> {\n  return new Promise(resolve => {\n    let data = '';\n    stream.setEncoding('utf8');\n    stream.on('data', (chunk: string) => {\n      data += chunk;\n    });\n    stream.on('end', () => {\n      try {\n        resolve(JSON.parse(data) as HookEvent);\n      } catch {\n        resolve({});\n      }\n    });\n    stream.on('error', () => {\n      resolve({});\n    });\n  });\n}\n\n/**\n * Which transcript lastReply should read, per the hook event: transcript_path\n * when it names a real file, else session_id, else nothing (lastReply then\n * falls back to the newest session for the current project).\n */\nexport function replyTarget(event: HookEvent): string | undefined {\n  if (event.transcript_path !== undefined && isFile(event.transcript_path)) {\n    return event.transcript_path;\n  }\n  return event.session_id || undefined;\n}\n\nfunction isFile(path: string): boolean {\n  try {\n    return statSync(path).isFile();\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Print the UserPromptExpansion decision for a zero-token command: `block`\n * keeps the command from reaching the model, with the output as the `reason`.\n */\nexport function emitHookBlock(reason: string): void {\n  process.stdout.write(`${JSON.stringify({ decision: 'block', reason })}\\n`);\n}\n","import type { HookEvent } from './hook.js';\n\nimport { emitHookBlock, readHookEvent } from './hook.js';\n\nimport type { Command } from 'commander';\n\nexport function parseQuietly(\n  program: Command,\n  args: readonly string[],\n): Command | undefined {\n  try {\n    program\n      .allowExcessArguments(false)\n      .exitOverride()\n      .configureOutput({ writeOut: () => undefined, writeErr: () => undefined })\n      .parse([...args], { from: 'user' });\n    return program;\n  } catch {\n    return undefined;\n  }\n}\n\nexport function printUsageAndExit(program: Command): never {\n  console.error(program.helpInformation());\n  // CLIs report failure through the exit code; the rule targets libraries.\n  // eslint-disable-next-line n/no-process-exit\n  process.exit(1);\n}\n\nexport async function hookOrPrint(\n  hook: boolean,\n  failure: string,\n  run: (event: HookEvent | undefined) => Promise<string> | string,\n  stdin: NodeJS.ReadableStream = process.stdin,\n): Promise<void> {\n  if (hook) {\n    let reason: string;\n    try {\n      reason = await run(await readHookEvent(stdin));\n    } catch (e) {\n      reason = `${failure}: ${(e as Error).message}`;\n    }\n    emitHookBlock(reason);\n    return;\n  }\n  try {\n    console.log(await run(undefined));\n  } catch (e) {\n    console.error((e as Error).message);\n    // CLIs report failure through the exit code; the rule targets libraries.\n    // eslint-disable-next-line n/no-process-exit\n    process.exit(1);\n  }\n}\n","import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';\nimport { homedir } from 'node:os';\nimport { join } from 'node:path';\n\ninterface ContentBlock {\n  text?: string;\n  type: string;\n}\n\ninterface TranscriptEntry {\n  message?: { content?: unknown };\n  type?: string;\n}\n\nfunction isFile(path: string): boolean {\n  try {\n    return statSync(path).isFile();\n  } catch {\n    return false;\n  }\n}\n\nfunction textBlocks(entry: TranscriptEntry): ContentBlock[] | undefined {\n  const content = entry.message?.content;\n  if (entry.type !== 'assistant' || !Array.isArray(content)) {\n    return undefined;\n  }\n  const blocks = content.filter(\n    (b): b is ContentBlock =>\n      typeof b === 'object' &&\n      b !== null &&\n      (b as ContentBlock).type === 'text',\n  );\n  return blocks.length > 0 ? blocks : undefined;\n}\n\n/**\n * The last assistant text reply from a Claude Code session, reproducing Claude\n * Code's `/copy` byte-for-byte: the last assistant entry that contains a\n * `text` block, only its `text` block(s) (tool_use / thinking dropped), blocks\n * joined with a blank line, and no trailing newline.\n *\n * @param arg a transcript file, a session UUID under the project dir, or\n *   nothing to use the newest session for the current project.\n */\nexport function lastReply(arg?: string): string {\n  const claudeDir = process.env.CLAUDE_DIR ?? join(homedir(), '.claude');\n  // Claude Code keys transcripts under the project root with \"/\" → \"-\".\n  // Prefer $CLAUDE_PROJECT_DIR (exported to hook processes) over $PWD.\n  const proj = (process.env.CLAUDE_PROJECT_DIR ?? process.cwd()).replaceAll(\n    '/',\n    '-',\n  );\n  const projDir = join(claudeDir, 'projects', proj);\n\n  let file: string | undefined;\n  if (arg !== undefined) {\n    file = isFile(arg) ? arg : join(projDir, `${arg}.jsonl`);\n  } else if (existsSync(projDir)) {\n    const newest = readdirSync(projDir)\n      .filter(f => f.endsWith('.jsonl'))\n      .map(f => ({ f, mtimeMs: statSync(join(projDir, f)).mtimeMs }))\n      .sort((a, b) => b.mtimeMs - a.mtimeMs)\n      .at(0);\n    if (newest) {\n      file = join(projDir, newest.f);\n    }\n  }\n\n  if (file === undefined || !isFile(file)) {\n    throw new Error(`no session transcript found in ${projDir}`);\n  }\n\n  let last: ContentBlock[] | undefined;\n  for (const line of readFileSync(file, 'utf8').split('\\n')) {\n    if (!line.includes('\"assistant\"')) {\n      continue;\n    }\n    let entry: TranscriptEntry;\n    try {\n      entry = JSON.parse(line) as TranscriptEntry;\n    } catch {\n      continue;\n    }\n    const blocks = textBlocks(entry);\n    if (blocks) {\n      last = blocks;\n    }\n  }\n  return (last ?? []).map(b => b.text ?? '').join('\\n\\n');\n}\n","/**\n * Plain-text rendering primitives shared by the zai and tokens report\n * renderers. Output targets a monospace terminal / hook-block `reason`, so\n * everything here is fixed-width: padding, block-glyph bars, and compact\n * number formatting.\n */\n\nexport const MONTHS = [\n  'Jan',\n  'Feb',\n  'Mar',\n  'Apr',\n  'May',\n  'Jun',\n  'Jul',\n  'Aug',\n  'Sep',\n  'Oct',\n  'Nov',\n  'Dec',\n];\n\nconst EIGHTHS = ['', '▏', '▎', '▍', '▌', '▋', '▊', '▉'];\n\nexport function fmtTokens(n: null | number | undefined): string {\n  if (n == null || Number.isNaN(n)) {\n    return '—';\n  }\n  if (n >= 1e9) {\n    return (n / 1e9).toFixed(1) + 'B';\n  }\n  if (n >= 1e6) {\n    return (n / 1e6).toFixed(1) + 'M';\n  }\n  if (n >= 1e3) {\n    return (n / 1e3).toFixed(1) + 'K';\n  }\n  return String(n);\n}\n\nexport function fmtNum(n: null | number | undefined): string {\n  return (n || 0).toLocaleString('en-US');\n}\n\nexport function padR(s: string, n: number): string {\n  return s.length >= n ? s : s + ' '.repeat(n - s.length);\n}\n\nexport function padL(s: string, n: number): string {\n  return s.length >= n ? s : ' '.repeat(n - s.length) + s;\n}\n\n/** Fixed-width bar field (width cols): █ blocks + an eighth-fraction + trailing spaces. */\nexport function barField(v: number, max: number, width: number): string {\n  if (!v || v <= 0 || max <= 0) {\n    return ' '.repeat(width);\n  }\n  const scaled = (v / max) * width;\n  let full = Math.floor(scaled);\n  let fi = Math.round((scaled - full) * 8);\n  if (fi === 8) {\n    full += 1;\n    fi = 0;\n  }\n  if (full === 0 && fi === 0) {\n    fi = 1;\n  } // keep a sliver for any nonzero value\n  let s = '█'.repeat(Math.min(full, width));\n  if (full < width && fi > 0) {\n    s += EIGHTHS[fi];\n  }\n  if (s.length < width) {\n    s += ' '.repeat(width - s.length);\n  }\n  return s.slice(0, width);\n}\n\n/** Filled/empty meter: █ for used, ░ for remaining. */\nexport function meter(pct: number | undefined, width: number): string {\n  let filled = Math.round(((pct || 0) / 100) * width);\n  filled = Math.max(0, Math.min(width, filled));\n  return '█'.repeat(filled) + '░'.repeat(width - filled);\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":[],"sources":["../src/input.ts","../src/hook.ts","../src/cli.ts","../src/dev.ts","../src/last-reply.ts","../src/logger.ts","../src/shutdown.ts","../src/text-format.ts"],"sourcesContent":["import { readFileSync, statSync } from 'node:fs';\n\nexport function readAll(stream: NodeJS.ReadableStream): Promise<string> {\n  return new Promise((resolve, reject) => {\n    let data = '';\n    stream.setEncoding('utf8');\n    stream.on('data', (chunk: string) => {\n      data += chunk;\n    });\n    stream.on('end', () => {\n      resolve(data);\n    });\n    stream.on('error', reject);\n  });\n}\n\nexport function readStdin(\n  stream: NodeJS.ReadableStream = process.stdin,\n): Promise<string> {\n  return readAll(stream);\n}\n\n/** A markdown file's contents, with the CLI's no-such-file error. */\nexport function readMarkdownFile(path: string): string {\n  const stats = statSync(path, { throwIfNoEntry: false });\n  if (!stats?.isFile()) {\n    throw new Error(`no such file: ${path}`);\n  }\n  return readFileSync(path, 'utf8');\n}\n","import { statSync } from 'node:fs';\n\nimport { readAll } from './input.js';\n\nexport interface HookEvent {\n  cwd?: string;\n  session_id?: string;\n  transcript_path?: string;\n}\n\n/**\n * Read the Claude Code hook event JSON from stdin; empty or unparseable input\n * yields an empty event, never a thrown error — a hook must always answer.\n */\nexport function readHookEvent(\n  stream: NodeJS.ReadableStream = process.stdin,\n): Promise<HookEvent> {\n  return readAll(stream).then(\n    data => {\n      try {\n        return JSON.parse(data) as HookEvent;\n      } catch {\n        return {};\n      }\n    },\n    () => ({}),\n  );\n}\n\n/**\n * Which transcript lastReply should read, per the hook event: transcript_path\n * when it names a real file, else session_id, else nothing (lastReply then\n * falls back to the newest session for the current project).\n */\nexport function replyTarget(event: HookEvent): string | undefined {\n  if (event.transcript_path !== undefined && isFile(event.transcript_path)) {\n    return event.transcript_path;\n  }\n  return event.session_id || undefined;\n}\n\nexport function isFile(path: string): boolean {\n  try {\n    return statSync(path).isFile();\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Print the UserPromptExpansion decision for a zero-token command: `block`\n * keeps the command from reaching the model, with the output as the `reason`.\n */\nexport function emitHookBlock(reason: string): void {\n  process.stdout.write(`${JSON.stringify({ decision: 'block', reason })}\\n`);\n}\n","import type { HookEvent } from './hook.js';\n\nimport { emitHookBlock, readHookEvent } from './hook.js';\n\nimport type { Command } from 'commander';\n\nexport function parseQuietly<T = never>(\n  program: Command,\n  args: readonly string[],\n  recover?: (err: unknown) => T | undefined,\n): Command | T | undefined {\n  try {\n    program\n      .allowExcessArguments(false)\n      .exitOverride()\n      .configureOutput({ writeOut: () => undefined, writeErr: () => undefined })\n      .parse([...args], { from: 'user' });\n    return program;\n  } catch (err) {\n    return recover?.(err);\n  }\n}\n\nexport function printUsageAndExit(program: Command): never {\n  console.error(program.helpInformation());\n  // CLIs report failure through the exit code; the rule targets libraries.\n  // eslint-disable-next-line n/no-process-exit\n  process.exit(1);\n}\n\nexport async function hookOrPrint(\n  hook: boolean,\n  failure: string,\n  run: (event: HookEvent | undefined) => Promise<string> | string,\n  stdin: NodeJS.ReadableStream = process.stdin,\n): Promise<void> {\n  if (hook) {\n    let reason: string;\n    try {\n      reason = await run(await readHookEvent(stdin));\n    } catch (e) {\n      reason = `${failure}: ${(e as Error).message}`;\n    }\n    emitHookBlock(reason);\n    return;\n  }\n  try {\n    console.log(await run(undefined));\n  } catch (e) {\n    console.error((e as Error).message);\n    // CLIs report failure through the exit code; the rule targets libraries.\n    // eslint-disable-next-line n/no-process-exit\n    process.exit(1);\n  }\n}\n","// Structural stand-ins for vite's dev server and module runner — the shared\n// hot-reload wiring below must not pull vite into core's runtime surface; the\n// MCP packages pass their real instances through.\nexport interface ReloadableRunner {\n  readonly evaluatedModules: { clear(): void };\n  import<T>(entry: string): Promise<T>;\n}\n\nexport interface WatchableDevServer {\n  close(): Promise<unknown>;\n  readonly watcher: {\n    on(event: 'change', cb: (file: string) => void): unknown;\n  };\n}\n\nconst RELOAD_DEBOUNCE_MS = 150;\n\nconst IGNORED_SEGMENTS = ['/node_modules/', '/dist/', '/.git/', '/coverage/'];\n\nfunction shouldReload(file: string): boolean {\n  return IGNORED_SEGMENTS.every(seg => !file.includes(seg));\n}\n\n/**\n * Debounced file-change reloads, serialized via a promise chain: concurrent\n * saves never overlap, and a mid-reload save still produces a follow-up.\n */\nexport function watchWithReload(\n  vite: WatchableDevServer,\n  reload: () => Promise<void>,\n): void {\n  let chain: Promise<void> = Promise.resolve();\n  let timer: NodeJS.Timeout | undefined;\n  vite.watcher.on('change', file => {\n    if (!shouldReload(file)) {\n      return;\n    }\n    if (timer) {\n      clearTimeout(timer);\n    }\n    timer = setTimeout(() => {\n      timer = undefined;\n      chain = chain.then(reload);\n    }, RELOAD_DEBOUNCE_MS);\n  });\n}\n","import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';\nimport { homedir } from 'node:os';\nimport { join } from 'node:path';\n\nimport { isFile } from './hook.js';\n\ninterface ContentBlock {\n  text?: string;\n  type: string;\n}\n\ninterface TranscriptEntry {\n  message?: { content?: unknown };\n  type?: string;\n}\n\nfunction textBlocks(entry: TranscriptEntry): ContentBlock[] | undefined {\n  const content = entry.message?.content;\n  if (entry.type !== 'assistant' || !Array.isArray(content)) {\n    return undefined;\n  }\n  const blocks = content.filter(\n    (b): b is ContentBlock =>\n      typeof b === 'object' &&\n      b !== null &&\n      (b as ContentBlock).type === 'text',\n  );\n  return blocks.length > 0 ? blocks : undefined;\n}\n\nexport function claudeProjectsDir(): string {\n  const claudeDir = process.env.CLAUDE_DIR ?? join(homedir(), '.claude');\n  return join(claudeDir, 'projects');\n}\n\n/**\n * The last assistant text reply from a Claude Code session, reproducing Claude\n * Code's `/copy` byte-for-byte: the last assistant entry that contains a\n * `text` block, only its `text` block(s) (tool_use / thinking dropped), blocks\n * joined with a blank line, and no trailing newline.\n *\n * @param arg a transcript file, a session UUID under the project dir, or\n *   nothing to use the newest session for the current project.\n */\nexport function lastReply(arg?: string): string {\n  // Claude Code keys transcripts under the project root with \"/\" → \"-\".\n  // Prefer $CLAUDE_PROJECT_DIR (exported to hook processes) over $PWD.\n  const proj = (process.env.CLAUDE_PROJECT_DIR ?? process.cwd()).replaceAll(\n    '/',\n    '-',\n  );\n  const projDir = join(claudeProjectsDir(), proj);\n\n  let file: string | undefined;\n  if (arg !== undefined) {\n    file = isFile(arg) ? arg : join(projDir, `${arg}.jsonl`);\n  } else if (existsSync(projDir)) {\n    const newest = readdirSync(projDir)\n      .filter(f => f.endsWith('.jsonl'))\n      .map(f => ({ f, mtimeMs: statSync(join(projDir, f)).mtimeMs }))\n      .sort((a, b) => b.mtimeMs - a.mtimeMs)\n      .at(0);\n    if (newest) {\n      file = join(projDir, newest.f);\n    }\n  }\n\n  if (file === undefined || !isFile(file)) {\n    throw new Error(`no session transcript found in ${projDir}`);\n  }\n\n  let last: ContentBlock[] | undefined;\n  for (const line of readFileSync(file, 'utf8').split('\\n')) {\n    if (!line.includes('\"assistant\"')) {\n      continue;\n    }\n    let entry: TranscriptEntry;\n    try {\n      entry = JSON.parse(line) as TranscriptEntry;\n    } catch {\n      continue;\n    }\n    const blocks = textBlocks(entry);\n    if (blocks) {\n      last = blocks;\n    }\n  }\n  return (last ?? []).map(b => b.text ?? '').join('\\n\\n');\n}\n","export type LogLevel = 'debug' | 'error' | 'info' | 'silent' | 'warn';\n\nconst LEVEL_RANK: Record<LogLevel, number> = {\n  debug: 10,\n  info: 20,\n  warn: 30,\n  error: 40,\n  silent: Number.MAX_SAFE_INTEGER,\n};\n\nexport function levelEnabled(\n  active: LogLevel,\n  wanted: Exclude<LogLevel, 'silent'>,\n): boolean {\n  return LEVEL_RANK[wanted] >= LEVEL_RANK[active];\n}\n\nconst LEVEL_LABEL: Record<Exclude<LogLevel, 'silent'>, string> = {\n  debug: 'DEBUG',\n  error: 'ERROR',\n  info: 'INFO',\n  warn: 'WARN',\n};\n\ntype Writer = (message: string) => void;\n\n// stdout carries the MCP transport; everything here goes to stderr.\nexport class Logger {\n  private readonly stderr: Writer;\n\n  constructor(\n    readonly activeLevel: LogLevel,\n    stderr: Writer = line => process.stderr.write(`${line}\\n`),\n  ) {\n    this.stderr = stderr;\n  }\n\n  debug(message: string): void {\n    this.log('debug', message);\n  }\n\n  error(message: string): void {\n    this.log('error', message);\n  }\n\n  info(message: string): void {\n    this.log('info', message);\n  }\n\n  warn(message: string): void {\n    this.log('warn', message);\n  }\n\n  private log(level: Exclude<LogLevel, 'silent'>, message: string): void {\n    if (levelEnabled(this.activeLevel, level)) {\n      this.stderr(`${LEVEL_LABEL[level]} ${message}`);\n    }\n  }\n}\n","/** Close each closable in order (best-effort), then force-exit. */\nexport function shutdownOnSignals(\n  closables: readonly { close(): Promise<unknown> }[],\n  signals: readonly NodeJS.Signals[] = ['SIGINT', 'SIGTERM'],\n): void {\n  const shutdown = (): void => {\n    void closables\n      .reduce(\n        (acc: Promise<void>, closable) =>\n          acc.then(async () => {\n            try {\n              await closable.close();\n            } catch {\n              // best-effort; exiting regardless\n            }\n          }),\n        Promise.resolve(),\n      )\n      .finally(() => {\n        // Force-exit on signal; the n/no-process-exit rule targets libraries.\n        // eslint-disable-next-line n/no-process-exit\n        process.exit(0);\n      });\n  };\n  for (const signal of signals) {\n    process.on(signal, shutdown);\n  }\n}\n","/**\n * Plain-text rendering primitives shared by the zai and tokens report\n * renderers. Output targets a monospace terminal / hook-block `reason`, so\n * everything here is fixed-width: padding, block-glyph bars, and compact\n * number formatting.\n */\n\nexport const MONTHS = [\n  'Jan',\n  'Feb',\n  'Mar',\n  'Apr',\n  'May',\n  'Jun',\n  'Jul',\n  'Aug',\n  'Sep',\n  'Oct',\n  'Nov',\n  'Dec',\n];\n\nconst EIGHTHS = ['', '▏', '▎', '▍', '▌', '▋', '▊', '▉'];\n\nexport const RULE_WIDTH = 68;\n\nexport function rule(): string {\n  return '─'.repeat(RULE_WIDTH);\n}\n\nexport function pad2(n: number): string {\n  return String(n).padStart(2, '0');\n}\n\n/** Local-time `YYYY-MM-DD` key. */\nexport function ymd(date: Date): string {\n  return `${date.getFullYear()}-${pad2(date.getMonth() + 1)}-${pad2(date.getDate())}`;\n}\n\nexport function fmtTokens(n: null | number | undefined): string {\n  if (n == null || Number.isNaN(n)) {\n    return '—';\n  }\n  if (n >= 1e9) {\n    return (n / 1e9).toFixed(1) + 'B';\n  }\n  if (n >= 1e6) {\n    return (n / 1e6).toFixed(1) + 'M';\n  }\n  if (n >= 1e3) {\n    return (n / 1e3).toFixed(1) + 'K';\n  }\n  return String(n);\n}\n\nexport function fmtNum(n: null | number | undefined): string {\n  return (n || 0).toLocaleString('en-US');\n}\n\nexport function padR(s: string, n: number): string {\n  return s.length >= n ? s : s + ' '.repeat(n - s.length);\n}\n\nexport function padL(s: string, n: number): string {\n  return s.length >= n ? s : ' '.repeat(n - s.length) + s;\n}\n\n/** Fixed-width bar field (width cols): █ blocks + an eighth-fraction + trailing spaces. */\nexport function barField(v: number, max: number, width: number): string {\n  if (!v || v <= 0 || max <= 0) {\n    return ' '.repeat(width);\n  }\n  const scaled = (v / max) * width;\n  let full = Math.floor(scaled);\n  let fi = Math.round((scaled - full) * 8);\n  if (fi === 8) {\n    full += 1;\n    fi = 0;\n  }\n  if (full === 0 && fi === 0) {\n    fi = 1;\n  } // keep a sliver for any nonzero value\n  let s = '█'.repeat(Math.min(full, width));\n  if (full < width && fi > 0) {\n    s += EIGHTHS[fi];\n  }\n  if (s.length < width) {\n    s += ' '.repeat(width - s.length);\n  }\n  return s.slice(0, width);\n}\n\n/** Filled/empty meter: █ for used, ░ for remaining. */\nexport function meter(pct: number | undefined, width: number): string {\n  let filled = Math.round(((pct || 0) / 100) * width);\n  filled = Math.max(0, Math.min(width, filled));\n  return '█'.repeat(filled) + '░'.repeat(width - filled);\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@v1nvn/agentic-core",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "Shared runtime for the @v1nvn agent tools — last-reply transcript reader and fixed-width text formatting.",
   "type": "module",
   "main": "./dist/index.js",
@@ -20,7 +20,10 @@
     "transcripts",
     "cli"
   ],
-  "author": "v1nvn",
+  "author": {
+    "name": "v1nvn",
+    "email": "v1n@outlook.com"
+  },
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/cli.ts

@@ -4,10 +4,11 @@ import { emitHookBlock, readHookEvent } from './hook.js';
 
 import type { Command } from 'commander';
 
-export function parseQuietly(
+export function parseQuietly<T = never>(
   program: Command,
   args: readonly string[],
-): Command | undefined {
+  recover?: (err: unknown) => T | undefined,
+): Command | T | undefined {
   try {
     program
       .allowExcessArguments(false)
@@ -15,8 +16,8 @@ export function parseQuietly(
       .configureOutput({ writeOut: () => undefined, writeErr: () => undefined })
       .parse([...args], { from: 'user' });
     return program;
-  } catch {
-    return undefined;
+  } catch (err) {
+    return recover?.(err);
   }
 }
 

package/src/dev.ts

@@ -0,0 +1,46 @@
+// Structural stand-ins for vite's dev server and module runner — the shared
+// hot-reload wiring below must not pull vite into core's runtime surface; the
+// MCP packages pass their real instances through.
+export interface ReloadableRunner {
+  readonly evaluatedModules: { clear(): void };
+  import<T>(entry: string): Promise<T>;
+}
+
+export interface WatchableDevServer {
+  close(): Promise<unknown>;
+  readonly watcher: {
+    on(event: 'change', cb: (file: string) => void): unknown;
+  };
+}
+
+const RELOAD_DEBOUNCE_MS = 150;
+
+const IGNORED_SEGMENTS = ['/node_modules/', '/dist/', '/.git/', '/coverage/'];
+
+function shouldReload(file: string): boolean {
+  return IGNORED_SEGMENTS.every(seg => !file.includes(seg));
+}
+
+/**
+ * Debounced file-change reloads, serialized via a promise chain: concurrent
+ * saves never overlap, and a mid-reload save still produces a follow-up.
+ */
+export function watchWithReload(
+  vite: WatchableDevServer,
+  reload: () => Promise<void>,
+): void {
+  let chain: Promise<void> = Promise.resolve();
+  let timer: NodeJS.Timeout | undefined;
+  vite.watcher.on('change', file => {
+    if (!shouldReload(file)) {
+      return;
+    }
+    if (timer) {
+      clearTimeout(timer);
+    }
+    timer = setTimeout(() => {
+      timer = undefined;
+      chain = chain.then(reload);
+    }, RELOAD_DEBOUNCE_MS);
+  });
+}

package/src/hook.ts

@@ -1,5 +1,7 @@
 import { statSync } from 'node:fs';
 
+import { readAll } from './input.js';
+
 export interface HookEvent {
   cwd?: string;
   session_id?: string;
@@ -13,23 +15,16 @@ export interface HookEvent {
 export function readHookEvent(
   stream: NodeJS.ReadableStream = process.stdin,
 ): Promise<HookEvent> {
-  return new Promise(resolve => {
-    let data = '';
-    stream.setEncoding('utf8');
-    stream.on('data', (chunk: string) => {
-      data += chunk;
-    });
-    stream.on('end', () => {
+  return readAll(stream).then(
+    data => {
       try {
-        resolve(JSON.parse(data) as HookEvent);
+        return JSON.parse(data) as HookEvent;
       } catch {
-        resolve({});
+        return {};
       }
-    });
-    stream.on('error', () => {
-      resolve({});
-    });
-  });
+    },
+    () => ({}),
+  );
 }
 
 /**
@@ -44,7 +39,7 @@ export function replyTarget(event: HookEvent): string | undefined {
   return event.session_id || undefined;
 }
 
-function isFile(path: string): boolean {
+export function isFile(path: string): boolean {
   try {
     return statSync(path).isFile();
   } catch {

package/src/index.ts

@@ -1,4 +1,8 @@
 export * from './cli.js';
+export * from './dev.js';
 export * from './hook.js';
+export * from './input.js';
 export * from './last-reply.js';
+export * from './logger.js';
+export * from './shutdown.js';
 export * from './text-format.js';

package/src/input.ts

@@ -0,0 +1,30 @@
+import { readFileSync, statSync } from 'node:fs';
+
+export function readAll(stream: NodeJS.ReadableStream): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    stream.setEncoding('utf8');
+    stream.on('data', (chunk: string) => {
+      data += chunk;
+    });
+    stream.on('end', () => {
+      resolve(data);
+    });
+    stream.on('error', reject);
+  });
+}
+
+export function readStdin(
+  stream: NodeJS.ReadableStream = process.stdin,
+): Promise<string> {
+  return readAll(stream);
+}
+
+/** A markdown file's contents, with the CLI's no-such-file error. */
+export function readMarkdownFile(path: string): string {
+  const stats = statSync(path, { throwIfNoEntry: false });
+  if (!stats?.isFile()) {
+    throw new Error(`no such file: ${path}`);
+  }
+  return readFileSync(path, 'utf8');
+}

package/src/last-reply.ts

@@ -2,6 +2,8 @@ import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
+import { isFile } from './hook.js';
+
 interface ContentBlock {
   text?: string;
   type: string;
@@ -12,14 +14,6 @@ interface TranscriptEntry {
   type?: string;
 }
 
-function isFile(path: string): boolean {
-  try {
-    return statSync(path).isFile();
-  } catch {
-    return false;
-  }
-}
-
 function textBlocks(entry: TranscriptEntry): ContentBlock[] | undefined {
   const content = entry.message?.content;
   if (entry.type !== 'assistant' || !Array.isArray(content)) {
@@ -34,6 +28,11 @@ function textBlocks(entry: TranscriptEntry): ContentBlock[] | undefined {
   return blocks.length > 0 ? blocks : undefined;
 }
 
+export function claudeProjectsDir(): string {
+  const claudeDir = process.env.CLAUDE_DIR ?? join(homedir(), '.claude');
+  return join(claudeDir, 'projects');
+}
+
 /**
  * The last assistant text reply from a Claude Code session, reproducing Claude
  * Code's `/copy` byte-for-byte: the last assistant entry that contains a
@@ -44,14 +43,13 @@ function textBlocks(entry: TranscriptEntry): ContentBlock[] | undefined {
  *   nothing to use the newest session for the current project.
  */
 export function lastReply(arg?: string): string {
-  const claudeDir = process.env.CLAUDE_DIR ?? join(homedir(), '.claude');
   // Claude Code keys transcripts under the project root with "/" → "-".
   // Prefer $CLAUDE_PROJECT_DIR (exported to hook processes) over $PWD.
   const proj = (process.env.CLAUDE_PROJECT_DIR ?? process.cwd()).replaceAll(
     '/',
     '-',
   );
-  const projDir = join(claudeDir, 'projects', proj);
+  const projDir = join(claudeProjectsDir(), proj);
 
   let file: string | undefined;
   if (arg !== undefined) {

package/src/logger.ts

@@ -0,0 +1,59 @@
+export type LogLevel = 'debug' | 'error' | 'info' | 'silent' | 'warn';
+
+const LEVEL_RANK: Record<LogLevel, number> = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40,
+  silent: Number.MAX_SAFE_INTEGER,
+};
+
+export function levelEnabled(
+  active: LogLevel,
+  wanted: Exclude<LogLevel, 'silent'>,
+): boolean {
+  return LEVEL_RANK[wanted] >= LEVEL_RANK[active];
+}
+
+const LEVEL_LABEL: Record<Exclude<LogLevel, 'silent'>, string> = {
+  debug: 'DEBUG',
+  error: 'ERROR',
+  info: 'INFO',
+  warn: 'WARN',
+};
+
+type Writer = (message: string) => void;
+
+// stdout carries the MCP transport; everything here goes to stderr.
+export class Logger {
+  private readonly stderr: Writer;
+
+  constructor(
+    readonly activeLevel: LogLevel,
+    stderr: Writer = line => process.stderr.write(`${line}\n`),
+  ) {
+    this.stderr = stderr;
+  }
+
+  debug(message: string): void {
+    this.log('debug', message);
+  }
+
+  error(message: string): void {
+    this.log('error', message);
+  }
+
+  info(message: string): void {
+    this.log('info', message);
+  }
+
+  warn(message: string): void {
+    this.log('warn', message);
+  }
+
+  private log(level: Exclude<LogLevel, 'silent'>, message: string): void {
+    if (levelEnabled(this.activeLevel, level)) {
+      this.stderr(`${LEVEL_LABEL[level]} ${message}`);
+    }
+  }
+}

package/src/shutdown.ts

@@ -0,0 +1,28 @@
+/** Close each closable in order (best-effort), then force-exit. */
+export function shutdownOnSignals(
+  closables: readonly { close(): Promise<unknown> }[],
+  signals: readonly NodeJS.Signals[] = ['SIGINT', 'SIGTERM'],
+): void {
+  const shutdown = (): void => {
+    void closables
+      .reduce(
+        (acc: Promise<void>, closable) =>
+          acc.then(async () => {
+            try {
+              await closable.close();
+            } catch {
+              // best-effort; exiting regardless
+            }
+          }),
+        Promise.resolve(),
+      )
+      .finally(() => {
+        // Force-exit on signal; the n/no-process-exit rule targets libraries.
+        // eslint-disable-next-line n/no-process-exit
+        process.exit(0);
+      });
+  };
+  for (const signal of signals) {
+    process.on(signal, shutdown);
+  }
+}

package/src/text-format.ts

@@ -22,6 +22,21 @@ export const MONTHS = [
 
 const EIGHTHS = ['', '▏', '▎', '▍', '▌', '▋', '▊', '▉'];
 
+export const RULE_WIDTH = 68;
+
+export function rule(): string {
+  return '─'.repeat(RULE_WIDTH);
+}
+
+export function pad2(n: number): string {
+  return String(n).padStart(2, '0');
+}
+
+/** Local-time `YYYY-MM-DD` key. */
+export function ymd(date: Date): string {
+  return `${date.getFullYear()}-${pad2(date.getMonth() + 1)}-${pad2(date.getDate())}`;
+}
+
 export function fmtTokens(n: null | number | undefined): string {
   if (n == null || Number.isNaN(n)) {
     return '—';