@tjamescouch/niki 0.5.2 → 0.5.3

package/README.md

@@ -53,6 +53,7 @@ niki --budget 500000 --log /tmp/niki.log --state /tmp/niki-state.json -- claude
 | `--max-tool-calls <n>` | `30` | Max total tool calls per minute |
 | `--log <file>` | none | Append diagnostics to file |
 | `--state <file>` | none | Write exit-state JSON on completion |
+| `--metrics <file>` | none | Append session metrics as JSONL on exit (cumulative across runs) |
 | `--cooldown <seconds>` | `5` | Grace period after SIGTERM before SIGKILL |
 | `--abort-file <path>` | none | Poll this file for external abort signal |
 | `--poll-interval <ms>` | `1000` | Base poll interval for abort file (±30% jitter) |
@@ -85,6 +86,24 @@ When `--state` is provided, niki writes a JSON snapshot on exit:
 }
 ```
 
+
+## Metrics file
+
+When `--metrics` is provided, niki **appends** one JSON line per session exit. The file grows across restarts, giving you a full history:
+
+```bash
+# View last 5 sessions
+tail -5 /tmp/niki-metrics.jsonl | jq .
+
+# Total tokens across all sessions
+cat /tmp/niki-metrics.jsonl | jq -s '[.[].tokensTotal] | add'
+
+# Sessions killed by reason
+cat /tmp/niki-metrics.jsonl | jq -s 'group_by(.killedBy) | map({reason: .[0].killedBy, count: length})'
+```
+
+Each line contains the full session state plus `endedAt`, `budget`, and `timeoutS` for context.
+
 `killedBy` is one of: `"budget"`, `"timeout"`, `"rate-sends"`, `"rate-tools"`, `"abort"`, or `null` (clean exit).
 
 ## Security

package/bin/niki

@@ -21,7 +21,7 @@
  */
 
 import { spawn, execSync } from 'node:child_process';
-import { createWriteStream, writeFileSync, mkdirSync, existsSync, readFileSync } from 'node:fs';
+import { createWriteStream, writeFileSync, appendFileSync, mkdirSync, existsSync, readFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { parseArgs } from 'node:util';
 
@@ -40,12 +40,13 @@ Options:
   --max-tool-calls <n>    Max total tool calls per minute (default: 30)
   --stall-timeout <secs>  Kill after N seconds of no output (default: 60, 0=disabled)
   --startup-timeout <s>   Longer stall timeout until first output (default: 180, 0=use stall-timeout)
-  --dead-air-timeout <m>  Minutes of zero CPU + zero output before kill (default: 5, 0=disabled)
+  --dead-air-timeout <m>  Minutes of zero CPU + zero output before kill (default: 1440, 0=disabled)
   --max-nudges <n>        Max stdin nudge attempts before kill on stall (default: 3)
   --log <file>            Write diagnostics log to file
   --log-level <level>     Minimum log level: debug, info, warn, error (default: info)
   --log-json              Emit logs as JSON lines (for machine parsing)
   --state <file>          Write state JSON on exit (budget used, reason, etc.)
+  --metrics <file>        Append session metrics as JSONL on exit (cumulative across runs)
   --cooldown <seconds>    Grace period after SIGTERM before SIGKILL (default: 5)
   --abort-file <path>     Poll this file for external abort signal
   --poll-interval <ms>    Base poll interval in ms for abort file (default: 1000)
@@ -73,12 +74,13 @@ const { values: opts } = parseArgs({
     'max-tool-calls': { type: 'string', default: '30' },
     'stall-timeout': { type: 'string', default: '60' },
     'startup-timeout': { type: 'string', default: '180' },
-    'dead-air-timeout': { type: 'string', default: '5' },
+    'dead-air-timeout': { type: 'string', default: '1440' },
     'max-nudges':    { type: 'string', default: '3' },
     log:             { type: 'string' },
     'log-level':     { type: 'string', default: 'info' },
     'log-json':      { type: 'boolean', default: false },
     state:           { type: 'string' },
+    metrics:         { type: 'string' },
     cooldown:        { type: 'string', default: '5' },
     'abort-file':    { type: 'string' },
     'poll-interval': { type: 'string', default: '1000' },
@@ -101,6 +103,7 @@ const ABORT_FILE    = opts['abort-file'] ? resolve(opts['abort-file']) : null;
 const POLL_INTERVAL = parseInt(opts['poll-interval'], 10);
 const LOG_FILE      = opts.log;
 const STATE_FILE    = opts.state;
+const METRICS_FILE  = opts.metrics;
 const RESTART       = opts.restart;
 const MAX_RESTARTS  = parseInt(opts['max-restarts'], 10);
 const RESTART_DELAY_S = parseFloat(opts['restart-delay']);
@@ -179,6 +182,24 @@ function writeState() {
   }
 }
 
+function writeMetrics() {
+  if (!METRICS_FILE) return;
+  try {
+    const p = resolve(METRICS_FILE);
+    mkdirSync(dirname(p), { recursive: true });
+    // Append one JSON line per session — never overwrite, never truncate
+    const entry = JSON.stringify({
+      ...state,
+      endedAt: new Date().toISOString(),
+      budget: BUDGET,
+      timeoutS: TIMEOUT_S,
+    });
+    appendFileSync(p, entry + '\n');
+  } catch {
+    // Best effort — metrics are not worth crashing over
+  }
+}
+
 // --- Budget threshold warnings ---
 
 function checkBudgetThresholds() {
@@ -301,6 +322,21 @@ function killChild(reason) {
   if (killed || !child) return;
   killed = true;
   state.killedBy = reason;
+
+  // Make kill events unmissable in interleaved log streams
+  const banner = [
+    '',
+    '🦜 ══════════════════════════════════════════════',
+    `🦜  NIKI KILL — ${reason.toUpperCase()}`,
+    `🦜  tokens: ${state.tokensTotal.toLocaleString()}/${BUDGET.toLocaleString()} | duration: ${Math.round((Date.now() - new Date(state.startedAt).getTime()) / 1000)}s`,
+    `🦜  sends: ${state.sendCallsThisMinute}/${MAX_SENDS}/min | tools: ${state.toolCallsThisMinute}/${MAX_TOOL_CALLS}/min`,
+    '🦜 ══════════════════════════════════════════════',
+    '',
+  ];
+  for (const line of banner) {
+    process.stderr.write(`[niki] ${line}\n`);
+    if (logStream) logStream.write(line + '\n');
+  }
   log(`KILL — reason: ${reason} | tokens: ${state.tokensTotal}/${BUDGET} | sends: ${state.sendCallsThisMinute}/min | tools: ${state.toolCallsThisMinute}/min`, 'error');
 
   child.kill('SIGTERM');
@@ -687,6 +723,7 @@ function startChild() {
     const level = state.killedBy ? 'error' : (code === 0 ? 'info' : 'warn');
     log(`Exit — code: ${code} signal: ${signal} | tokens: ${state.tokensTotal.toLocaleString()} | tools: ${state.toolCalls} | sends: ${state.sendCalls} | duration: ${state.duration}s | output: ${gotFirstOutput}${state.killedBy ? ` | killed: ${state.killedBy}` : ''} | restarts: ${state.restarts}`, level);
     writeState();
+    writeMetrics();
 
     if (shouldRestart(code, signal)) {
       state.restarts++;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tjamescouch/niki",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "Deterministic process supervisor for AI agents — token budgets, rate limits, and abort control",
   "bin": {
     "niki": "./bin/niki"