@phnx-labs/agents-cli 1.22.104 → 1.22.106

package/dist/session-tracker/dist/reader.js

@@ -0,0 +1,151 @@
+import { exec } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import { promisify } from 'util';
+import { STATE_DIR, parseState, stateFilePath } from './state-file.js';
+const execAsync = promisify(exec);
+const PID_TREE_MAX_DEPTH = 5;
+const PID_TREE_MAX_NODES = 100;
+// macOS `pgrep -P` silently misses children for some pids; `ps -eo` is reliable.
+async function buildChildIndex() {
+    const index = new Map();
+    try {
+        const { stdout } = await execAsync('ps -eo pid,ppid', { timeout: 2000 });
+        for (const line of stdout.split('\n').slice(1)) {
+            const [pidStr, ppidStr] = line.trim().split(/\s+/);
+            const pid = Number(pidStr);
+            const ppid = Number(ppidStr);
+            if (!Number.isFinite(pid) || !Number.isFinite(ppid))
+                continue;
+            const kids = index.get(ppid);
+            if (kids)
+                kids.push(pid);
+            else
+                index.set(ppid, [pid]);
+        }
+    }
+    catch {
+        /* empty index — caller treats as no descendants */
+    }
+    return index;
+}
+export async function descendantPids(rootPid) {
+    const index = await buildChildIndex();
+    const visited = new Set([rootPid]);
+    const out = [];
+    const queue = [{ pid: rootPid, depth: 0 }];
+    while (queue.length > 0 && visited.size < PID_TREE_MAX_NODES) {
+        const { pid, depth } = queue.shift();
+        if (depth >= PID_TREE_MAX_DEPTH)
+            continue;
+        for (const c of index.get(pid) ?? []) {
+            if (visited.has(c))
+                continue;
+            visited.add(c);
+            out.push(c);
+            queue.push({ pid: c, depth: depth + 1 });
+            if (visited.size >= PID_TREE_MAX_NODES)
+                break;
+        }
+    }
+    return out;
+}
+export async function findStateByPid(pid) {
+    try {
+        const raw = await fs.promises.readFile(stateFilePath(pid), 'utf8');
+        return parseState(raw);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        return null;
+    }
+}
+export async function findStateInTree(shellPid) {
+    const pids = [shellPid, ...(await descendantPids(shellPid))];
+    let best = null;
+    for (const pid of pids) {
+        const s = await findStateByPid(pid);
+        if (s && (!best || s.ts > best.ts))
+            best = s;
+    }
+    return best;
+}
+async function scanAllStates() {
+    let names;
+    try {
+        names = await fs.promises.readdir(STATE_DIR);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of names) {
+        if (!name.endsWith('.json'))
+            continue;
+        try {
+            const raw = await fs.promises.readFile(path.join(STATE_DIR, name), 'utf8');
+            const s = parseState(raw);
+            if (s)
+                out.push(s);
+        }
+        catch {
+            /* skip */
+        }
+    }
+    return out;
+}
+export async function findStateByTerminalId(terminalId) {
+    const all = await scanAllStates();
+    let best = null;
+    for (const s of all) {
+        if (s.terminal_id !== terminalId)
+            continue;
+        if (!best || s.ts > best.ts)
+            best = s;
+    }
+    return best;
+}
+export async function findStateByLaunchId(launchId) {
+    const all = await scanAllStates();
+    let best = null;
+    for (const s of all) {
+        if (s.launch_id !== launchId)
+            continue;
+        if (!best || s.ts > best.ts)
+            best = s;
+    }
+    return best;
+}
+export async function pruneStaleSessionState() {
+    let names;
+    try {
+        names = await fs.promises.readdir(STATE_DIR);
+    }
+    catch {
+        return 0;
+    }
+    let removed = 0;
+    for (const name of names) {
+        if (!name.endsWith('.json'))
+            continue;
+        const pid = Number(name.slice(0, -5));
+        if (!Number.isFinite(pid) || pid <= 0)
+            continue;
+        try {
+            process.kill(pid, 0);
+        }
+        catch (err) {
+            if (err.code === 'ESRCH') {
+                try {
+                    await fs.promises.unlink(path.join(STATE_DIR, name));
+                    removed++;
+                }
+                catch {
+                    /* best-effort */
+                }
+            }
+        }
+    }
+    return removed;
+}

package/dist/session-tracker/dist/state-file.d.ts

@@ -0,0 +1,10 @@
+import type { SessionState } from './types.js';
+export declare const STATE_DIR: string;
+export declare function stateFilePath(pid: number, stateDir?: string): string;
+export declare function serializeState(s: SessionState): string;
+export declare function parseState(raw: string): SessionState | null;
+export declare function writeStateAtomic(state: SessionState, stateDir?: string): Promise<void>;
+/** Remove stale state files: dead-pid records, zero-byte JSON files, and orphaned
+ *  temp files left behind by failed atomic writes. Returns the number of files
+ *  removed. Best-effort: individual failures are ignored and do not stop the sweep. */
+export declare function cleanupOrphanedStateFiles(stateDir?: string): Promise<number>;

package/dist/session-tracker/dist/state-file.js

@@ -0,0 +1,119 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+export const STATE_DIR = path.join(os.homedir(), '.agents', '.cache', 'terminals', 'sessions');
+export function stateFilePath(pid, stateDir = STATE_DIR) {
+    return path.join(stateDir, `${pid}.json`);
+}
+const KEY_ORDER = [
+    'session_id',
+    'agent',
+    'cwd',
+    'pid',
+    'terminal_id',
+    'launch_id',
+    'ts',
+    'method',
+];
+export function serializeState(s) {
+    const ordered = {};
+    for (const k of KEY_ORDER) {
+        const v = s[k];
+        if (v !== undefined)
+            ordered[k] = v;
+    }
+    return JSON.stringify(ordered);
+}
+export function parseState(raw) {
+    let obj;
+    try {
+        obj = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!obj || typeof obj !== 'object')
+        return null;
+    const o = obj;
+    if (typeof o.session_id !== 'string' ||
+        typeof o.cwd !== 'string' ||
+        typeof o.pid !== 'number' ||
+        typeof o.ts !== 'number') {
+        return null;
+    }
+    // Legacy 04-capture hook omits agent + method. Default rather than reject.
+    if (typeof o.agent !== 'string')
+        o.agent = 'unknown';
+    if (typeof o.method !== 'string')
+        o.method = 'hook-stdin';
+    return o;
+}
+export async function writeStateAtomic(state, stateDir = STATE_DIR) {
+    await fs.promises.mkdir(stateDir, { recursive: true });
+    const finalPath = stateFilePath(state.pid, stateDir);
+    const tmpPath = `${finalPath}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        await fs.promises.writeFile(tmpPath, serializeState(state), 'utf8');
+        await fs.promises.rename(tmpPath, finalPath);
+    }
+    catch (err) {
+        try {
+            await fs.promises.unlink(tmpPath);
+        }
+        catch { /* best-effort */ }
+        throw err;
+    }
+}
+const PID_JSON_RE = /^(\d+)\.json$/;
+const PID_TEMP_RE = /^\.(\d+)\.[^.]+$/;
+/** Remove stale state files: dead-pid records, zero-byte JSON files, and orphaned
+ *  temp files left behind by failed atomic writes. Returns the number of files
+ *  removed. Best-effort: individual failures are ignored and do not stop the sweep. */
+export async function cleanupOrphanedStateFiles(stateDir = STATE_DIR) {
+    let names;
+    try {
+        names = await fs.promises.readdir(stateDir);
+    }
+    catch {
+        return 0;
+    }
+    let removed = 0;
+    for (const name of names) {
+        const full = path.join(stateDir, name);
+        let stat;
+        try {
+            stat = await fs.promises.stat(full);
+        }
+        catch {
+            continue;
+        }
+        // Zero-byte JSON files are never valid state records.
+        if (stat.size === 0 && name.endsWith('.json')) {
+            try {
+                await fs.promises.unlink(full);
+                removed++;
+            }
+            catch { /* ignore race */ }
+            continue;
+        }
+        const pidMatch = PID_JSON_RE.exec(name) ?? PID_TEMP_RE.exec(name);
+        if (!pidMatch)
+            continue;
+        const pid = Number(pidMatch[1]);
+        if (!Number.isFinite(pid) || pid <= 0)
+            continue;
+        try {
+            process.kill(pid, 0);
+        }
+        catch (err) {
+            if (err.code === 'ESRCH') {
+                try {
+                    await fs.promises.unlink(full);
+                    removed++;
+                }
+                catch { /* ignore race */ }
+            }
+        }
+    }
+    return removed;
+}

package/dist/session-tracker/dist/types.d.ts

@@ -0,0 +1,32 @@
+export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'grok' | 'kimi' | 'droid' | 'antigravity' | 'opencode' | 'hermes';
+export interface TrackSpawnInput {
+    agent: AgentId;
+    agentPid: number;
+    shellPid?: number;
+    cwd: string;
+    terminalId?: string;
+    launchId: string;
+}
+export type DetectionMethod = 'hook-stdin' | 'hook-env' | 'fs-watch' | 'stdout-banner';
+export type DetectionConfidence = 'high' | 'medium' | 'low';
+export interface DetectionResult {
+    sessionId: string | null;
+    method: DetectionMethod | null;
+    latencyMs: number;
+    confidence: DetectionConfidence;
+}
+export interface SessionState {
+    session_id: string;
+    agent: AgentId;
+    cwd: string;
+    pid: number;
+    terminal_id?: string;
+    launch_id?: string;
+    ts: number;
+    method: DetectionMethod;
+}
+export interface LookupInput {
+    shellPid?: number;
+    terminalId?: string;
+    launchId?: string;
+}

package/dist/session-tracker/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/session-tracker/dist/writer.d.ts

@@ -0,0 +1,12 @@
+import type { AgentId, DetectionMethod } from './types.js';
+export interface RecordSessionArgs {
+    sessionId: string;
+    agent: AgentId;
+    pid: number;
+    cwd: string;
+    terminalId?: string;
+    launchId?: string;
+    method: DetectionMethod;
+}
+export declare function recordSession(args: RecordSessionArgs): Promise<void>;
+export declare function clearSession(pid: number): Promise<void>;

package/dist/session-tracker/dist/writer.js

@@ -0,0 +1,27 @@
+import * as fs from 'fs';
+import { stateFilePath, writeStateAtomic } from './state-file.js';
+export async function recordSession(args) {
+    const state = {
+        session_id: args.sessionId,
+        agent: args.agent,
+        cwd: args.cwd,
+        pid: args.pid,
+        ts: Date.now(),
+        method: args.method,
+    };
+    if (args.terminalId)
+        state.terminal_id = args.terminalId;
+    if (args.launchId)
+        state.launch_id = args.launchId;
+    await writeStateAtomic(state);
+}
+export async function clearSession(pid) {
+    try {
+        await fs.promises.unlink(stateFilePath(pid));
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT') {
+            throw err;
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.22.104",
+  "version": "1.22.106",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",