@phnx-labs/agents-cli 0.1.0 → 1.14.1

package/dist/lib/session/artifacts.js

@@ -1,9 +1,18 @@
+/**
+ * Session artifact discovery and resolution.
+ *
+ * Scans parsed session events for file-write tool calls (Write, Edit, etc.)
+ * and returns metadata about each artifact: path, authoring tool, existence
+ * on disk, and file size. Used by the artifacts subcommand and session detail views.
+ */
 import * as fs from 'fs';
 import * as path from 'path';
 import { parseSession } from './parse.js';
+/** Tool names that produce file artifacts (writes, edits, patches). */
 const WRITE_TOOLS = new Set([
     'Write', 'Edit', 'write_file', 'edit_file', 'create_file', 'replace', 'patch',
 ]);
+/** Parse a session and return metadata for every file written or edited during it. */
 export function discoverArtifacts(meta) {
     let events;
     try {
@@ -34,12 +43,14 @@ export function discoverArtifacts(meta) {
         let exists = false;
         let sizeBytes;
         try {
-            const stat = fs.statSync(p);
-            exists = true;
-            sizeBytes = stat.size;
+            const stat = fs.lstatSync(p);
+            if (stat.isFile()) {
+                exists = true;
+                sizeBytes = stat.size;
+            }
         }
         catch {
-            // file gone or inaccessible
+            // file gone, inaccessible, or symlink/special file
         }
         artifacts.push({
             path: p,
@@ -52,9 +63,19 @@ export function discoverArtifacts(meta) {
     }
     return artifacts;
 }
+/** Refuse to load artifact files larger than this. Returns '' silently above the cap. */
+export const ARTIFACT_MAX_BYTES = 50_000_000;
+/** Read the current contents of an artifact file from disk. Rejects symlinks. */
 export function readArtifact(artifact) {
+    const stat = fs.lstatSync(artifact.path);
+    if (!stat.isFile()) {
+        throw new Error(`Refusing to read non-regular file: ${artifact.path}`);
+    }
+    if (stat.size > ARTIFACT_MAX_BYTES)
+        return '';
     return fs.readFileSync(artifact.path, 'utf-8');
 }
+/** Resolve a user-provided name to an artifact by exact path, basename, or path suffix. */
 export function resolveArtifact(artifacts, name) {
     // Exact path match
     const exact = artifacts.find(a => a.path === name);
@@ -72,4 +93,3 @@ export function resolveArtifact(artifacts, name) {
         return bySuffix[0];
     return null;
 }
-//# sourceMappingURL=artifacts.js.map

package/dist/lib/session/cloud.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Rush Cloud session source.
+ *
+ * Fetches cloud-captured sessions from halo/proxy (api.prix.dev) and caches
+ * them locally so the existing filesystem-based parse pipeline works unchanged.
+ *
+ * Endpoints consumed (implemented in halo/proxy/src/cloud-runs.ts):
+ *   GET /api/v1/cloud-runs                  → list executions
+ *   GET /api/v1/cloud-runs/:id              → get one (used for meta)
+ *   GET /api/v1/cloud-runs/:id/session.jsonl → raw captured jsonl
+ */
+import type { SessionMeta } from './types.js';
+/**
+ * List cloud executions the user has captured sessions for. Includes
+ * completed + needs_review + failed; an empty session_path means capture
+ * never ran, so those are silently dropped.
+ */
+export declare function discoverCloudSessions(options?: {
+    limit?: number;
+}): Promise<SessionMeta[]>;
+/**
+ * Fetch the jsonl for one cloud execution and stash it in the local cache.
+ * Returns the local file path. Re-fetches on every call (cheap — executions
+ * are immutable once complete). Callers may pass an already-known filePath.
+ */
+export declare function ensureCloudSessionCached(executionId: string, destPath?: string): Promise<string>;
+/** True if filePath points into the cloud session cache dir. */
+export declare function isCloudSessionPath(filePath: string): boolean;
+/** Extract execution_id from a cloud cache path. */
+export declare function executionIdFromCloudPath(filePath: string): string | null;

package/dist/lib/session/cloud.js

@@ -0,0 +1,121 @@
+/**
+ * Rush Cloud session source.
+ *
+ * Fetches cloud-captured sessions from halo/proxy (api.prix.dev) and caches
+ * them locally so the existing filesystem-based parse pipeline works unchanged.
+ *
+ * Endpoints consumed (implemented in halo/proxy/src/cloud-runs.ts):
+ *   GET /api/v1/cloud-runs                  → list executions
+ *   GET /api/v1/cloud-runs/:id              → get one (used for meta)
+ *   GET /api/v1/cloud-runs/:id/session.jsonl → raw captured jsonl
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import * as yaml from 'yaml';
+import { getAgentsDir } from '../state.js';
+const PROXY_BASE = process.env.RUSH_PROXY_BASE ?? 'https://api.prix.dev';
+const USER_YAML = path.join(os.homedir(), '.rush', 'user.yaml');
+const CLOUD_CACHE_DIR = path.join(getAgentsDir(), 'cache', 'cloud-runs');
+function readToken() {
+    if (!fs.existsSync(USER_YAML)) {
+        throw new Error('Not logged in to Rush. Run `rush login` first.');
+    }
+    const raw = fs.readFileSync(USER_YAML, 'utf-8');
+    const data = yaml.parse(raw);
+    const token = data?.session?.access_token;
+    if (!token) {
+        throw new Error('No session token in ~/.rush/user.yaml. Run `rush login` first.');
+    }
+    return token;
+}
+async function api(method, endpoint, token) {
+    return fetch(`${PROXY_BASE}${endpoint}`, {
+        method,
+        headers: { Authorization: `Bearer ${token}` },
+    });
+}
+/** Coerce the `agent` field on a cloud-run row to a SessionAgentId. */
+function agentToFormat(agent) {
+    if (agent === 'claude')
+        return 'claude';
+    if (agent === 'codex')
+        return 'codex';
+    if (agent === 'rush')
+        return 'rush';
+    return null;
+}
+/**
+ * List cloud executions the user has captured sessions for. Includes
+ * completed + needs_review + failed; an empty session_path means capture
+ * never ran, so those are silently dropped.
+ */
+export async function discoverCloudSessions(options) {
+    const token = readToken();
+    const limit = options?.limit ?? 50;
+    const res = await api('GET', `/api/v1/cloud-runs?limit=${limit}`, token);
+    if (!res.ok) {
+        throw new Error(`cloud-runs list failed (${res.status})`);
+    }
+    const data = (await res.json());
+    const rows = data.executions ?? [];
+    const out = [];
+    for (const row of rows) {
+        const agent = agentToFormat(row.agent);
+        if (!agent)
+            continue;
+        const id = row.execution_id;
+        const timestamp = row.updated_at || row.created_at || new Date().toISOString();
+        const project = row.repo_owner && row.repo_name ? `${row.repo_owner}/${row.repo_name}` : undefined;
+        // filePath doubles as the sink path for the cached jsonl. parseSession
+        // dispatches on detectAgent which recognizes the `session.<format>.jsonl`
+        // suffix — so the local cache file name must preserve it.
+        const filePath = path.join(CLOUD_CACHE_DIR, id, `session.${agent}.jsonl`);
+        out.push({
+            id,
+            shortId: id.slice(0, 8),
+            agent,
+            timestamp,
+            project,
+            filePath,
+            topic: row.prompt?.split('\n')[0]?.slice(0, 120),
+            label: `[cloud/${row.status}]${row.branch ? ` ${row.branch}` : ''}`,
+        });
+    }
+    out.sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
+    return out;
+}
+/**
+ * Fetch the jsonl for one cloud execution and stash it in the local cache.
+ * Returns the local file path. Re-fetches on every call (cheap — executions
+ * are immutable once complete). Callers may pass an already-known filePath.
+ */
+export async function ensureCloudSessionCached(executionId, destPath) {
+    const token = readToken();
+    const res = await api('GET', `/api/v1/cloud-runs/${encodeURIComponent(executionId)}/session.jsonl`, token);
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throw new Error(`session.jsonl fetch ${res.status}: ${body.slice(0, 200)}`);
+    }
+    const format = (res.headers.get('X-Session-Format') || '').toLowerCase();
+    if (!['claude', 'codex', 'rush'].includes(format)) {
+        throw new Error(`Unknown X-Session-Format on cloud response: "${format}"`);
+    }
+    const finalPath = destPath ?? path.join(CLOUD_CACHE_DIR, executionId, `session.${format}.jsonl`);
+    fs.mkdirSync(path.dirname(finalPath), { recursive: true });
+    const body = Buffer.from(await res.arrayBuffer());
+    fs.writeFileSync(finalPath, body);
+    return finalPath;
+}
+/** True if filePath points into the cloud session cache dir. */
+export function isCloudSessionPath(filePath) {
+    return filePath.startsWith(CLOUD_CACHE_DIR);
+}
+/** Extract execution_id from a cloud cache path. */
+export function executionIdFromCloudPath(filePath) {
+    if (!isCloudSessionPath(filePath))
+        return null;
+    const rel = path.relative(CLOUD_CACHE_DIR, filePath);
+    const parts = rel.split(path.sep);
+    return parts[0] || null;
+}

package/dist/lib/session/db.d.ts

@@ -1,5 +1,14 @@
-import Database from 'better-sqlite3';
+/**
+ * SQLite-backed session index and full-text search.
+ *
+ * Stores session metadata and user-prompt text in a WAL-mode SQLite database
+ * at ~/.agents/sessions/sessions.db. Provides incremental upsert, scan-stamp
+ * ledger (mtime/size tracking to skip unchanged files), FTS5 search with
+ * BM25 ranking, and label-first search for /rename'd sessions.
+ */
+import Database from '../sqlite.js';
 import type { SessionAgentId, SessionMeta } from './types.js';
+/** Raw row shape returned from the sessions table. */
 export interface SessionRow {
     id: string;
     short_id: string;
@@ -20,10 +29,12 @@ export interface SessionRow {
     scanned_at: number | null;
     is_team_origin: number;
 }
+/** File stat snapshot used to detect changes between scan runs. */
 export interface ScanStamp {
     fileMtimeMs: number;
     fileSize: number;
 }
+/** Filter and pagination options for querying the sessions table. */
 export interface QueryOptions {
     agent?: SessionAgentId;
     agents?: SessionAgentId[];
@@ -40,8 +51,11 @@ export interface QueryOptions {
     /** Keep only team-origin rows (for hidden-count queries). */
     onlyTeamOrigin?: boolean;
 }
+/** Open (or return the cached) sessions database, applying migrations as needed. */
 export declare function getDB(): Database.Database;
+/** Close the cached database connection. */
 export declare function closeDB(): void;
+/** Return the absolute path to the sessions database file. */
 export declare function getDBPath(): string;
 /**
  * Look up the file stat stamp we stored the last time we scanned a given file path.
@@ -66,6 +80,7 @@ export declare function recordScans(entries: Array<{
  * `content` is the tokenizable user-prompt text; pass '' to leave the row unsearchable.
  */
 export declare function upsertSession(meta: SessionMeta, content: string, scan?: ScanStamp): void;
+/** Batch-upsert sessions with their FTS5 content and scan stamps in a single transaction. */
 export declare function upsertSessionsBatch(entries: Array<{
     meta: SessionMeta;
     content: string;
@@ -77,11 +92,17 @@ export declare function upsertSessionsBatch(entries: Array<{
  * Leaves FTS5 content/topic/project untouched — cheap to call every run.
  */
 export declare function syncLabels(labelMap: Map<string, string | null>): number;
+/** Query sessions from the database, applying filters and ordering by timestamp descending. */
 export declare function querySessions(options?: QueryOptions): SessionMeta[];
+/** Count sessions matching the given filter options. */
 export declare function countSessions(options?: QueryOptions): number;
+/** Return the set of all file paths currently tracked in the sessions table. */
 export declare function getAllFilePaths(): Set<string>;
+/** Look up sessions by their source file paths. */
 export declare function getSessionsByFilePaths(paths: string[]): Map<string, SessionMeta>;
+/** Look up a single session by its unique ID. */
 export declare function getSessionById(id: string): SessionMeta | null;
+/** A single full-text search result with ranking score. */
 export interface FtsHit {
     sessionId: string;
     score: number;
@@ -111,8 +132,8 @@ export declare function buildFtsQuery(input: string): {
  * so "higher = better" is consistent across all tiers.
  */
 export declare function ftsSearch(input: string, limit?: number): FtsHit[];
+/** Return the total row counts for the sessions and FTS5 tables (diagnostic). */
 export declare function getRowCount(): {
     sessions: number;
     textRows: number;
 };
-//# sourceMappingURL=db.d.ts.map

package/dist/lib/session/db.js

@@ -1,14 +1,43 @@
+/**
+ * SQLite-backed session index and full-text search.
+ *
+ * Stores session metadata and user-prompt text in a WAL-mode SQLite database
+ * at ~/.agents/sessions/sessions.db. Provides incremental upsert, scan-stamp
+ * ledger (mtime/size tracking to skip unchanged files), FTS5 search with
+ * BM25 ranking, and label-first search for /rename'd sessions.
+ */
 import * as fs from 'fs';
-import * as os from 'os';
 import * as path from 'path';
-import Database from 'better-sqlite3';
-const HOME = os.homedir();
-const SESSIONS_DIR = path.join(HOME, '.agents', 'sessions');
+import Database from '../sqlite.js';
+import { getAgentsDir } from '../state.js';
+const SESSIONS_DIR = path.join(getAgentsDir(), 'sessions');
 const DB_PATH = path.join(SESSIONS_DIR, 'sessions.db');
-const SCHEMA_VERSION = 4;
+/** Current schema version; bumped when migrations are added. */
+const SCHEMA_VERSION = 5;
+/**
+ * Canonicalize a file path for use as a scan_ledger key. The same physical
+ * session file is reachable via multiple aliases — `~/.claude/projects/x.jsonl`
+ * (when `~/.claude` is a symlink to a versioned home) and
+ * `~/.agents-system/versions/claude/<v>/home/.claude/projects/x.jsonl`. Keying the
+ * ledger by the raw path means switching between these aliases (e.g. via
+ * `agents use`) misses the cache and forces a full re-parse. Realpath collapses
+ * all aliases to one stable key.
+ */
+function canonicalLedgerKey(filePath) {
+    if (!filePath)
+        return filePath;
+    try {
+        return fs.realpathSync(filePath);
+    }
+    catch {
+        return filePath;
+    }
+}
 // BM25 column weights for session_text: label > topic > project > content.
 // Higher weights make matches in that column rank higher.
+/** BM25 column weights for FTS5: label > topic > project > content. */
 const BM25_WEIGHTS = [5.0, 2.0, 1.5, 1.0];
+/** DDL for the sessions database (tables, indexes, FTS5 virtual table). */
 const SCHEMA = `
 CREATE TABLE IF NOT EXISTS sessions (
   id TEXT PRIMARY KEY,
@@ -105,7 +134,15 @@ function migrateSchema(db, fromVersion) {
         }
         db.exec(`DELETE FROM scan_ledger;`);
     }
+    if (fromVersion < 5) {
+        // v4 → v5: ledger is now keyed by realpath instead of the as-discovered
+        // path, so symlink/version-relative aliases for the same physical file
+        // collapse to one row. Old aliased rows are dropped — next scan will
+        // repopulate under canonical keys.
+        db.exec(`DELETE FROM scan_ledger;`);
+    }
 }
+/** Open (or return the cached) sessions database, applying migrations as needed. */
 export function getDB() {
     if (dbInstance)
         return dbInstance;
@@ -144,12 +181,14 @@ export function getDB() {
     dbInstance = db;
     return db;
 }
+/** Close the cached database connection. */
 export function closeDB() {
     if (dbInstance) {
         dbInstance.close();
         dbInstance = null;
     }
 }
+/** Return the absolute path to the sessions database file. */
 export function getDBPath() {
     return DB_PATH;
 }
@@ -161,7 +200,7 @@ export function getScanStampByPath(filePath) {
     const db = getDB();
     const row = db
         .prepare(`SELECT file_mtime_ms, file_size FROM scan_ledger WHERE file_path = ? LIMIT 1`)
-        .get(filePath);
+        .get(canonicalLedgerKey(filePath));
     return row ? { fileMtimeMs: row.file_mtime_ms, fileSize: row.file_size } : null;
 }
 /**
@@ -173,10 +212,24 @@ export function getScanStampsForPaths(filePaths) {
     if (filePaths.length === 0)
         return result;
     const db = getDB();
+    // Multiple input paths can resolve to the same canonical key (e.g. the same
+    // session JSONL reachable via `~/.claude/...` and `~/.agents-system/versions/...`).
+    // We query DB by canonical key, then fan results back out to every original
+    // alias so callers can `.get(filePath)` with the path they passed in.
+    const canonicalToOriginals = new Map();
+    for (const fp of filePaths) {
+        const canonical = canonicalLedgerKey(fp);
+        const aliases = canonicalToOriginals.get(canonical);
+        if (aliases)
+            aliases.push(fp);
+        else
+            canonicalToOriginals.set(canonical, [fp]);
+    }
+    const canonicalKeys = [...canonicalToOriginals.keys()];
     // SQLite parameter limit is typically 999 / 32766 — chunk defensively.
     const CHUNK = 500;
-    for (let i = 0; i < filePaths.length; i += CHUNK) {
-        const chunk = filePaths.slice(i, i + CHUNK);
+    for (let i = 0; i < canonicalKeys.length; i += CHUNK) {
+        const chunk = canonicalKeys.slice(i, i + CHUNK);
         const placeholders = chunk.map(() => '?').join(',');
         const rows = db
             .prepare(`
@@ -186,7 +239,10 @@ export function getScanStampsForPaths(filePaths) {
       `)
             .all(...chunk);
         for (const row of rows) {
-            result.set(row.file_path, { fileMtimeMs: row.file_mtime_ms, fileSize: row.file_size });
+            const stamp = { fileMtimeMs: row.file_mtime_ms, fileSize: row.file_size };
+            for (const original of canonicalToOriginals.get(row.file_path) || []) {
+                result.set(original, stamp);
+            }
         }
     }
     return result;
@@ -210,7 +266,7 @@ export function recordScans(entries) {
     const now = Date.now();
     const txn = db.transaction((items) => {
         for (const { filePath, scan } of items) {
-            stmt.run(filePath, scan.fileMtimeMs, scan.fileSize, now);
+            stmt.run(canonicalLedgerKey(filePath), scan.fileMtimeMs, scan.fileSize, now);
         }
     });
     txn(entries);
@@ -291,6 +347,7 @@ export function upsertSession(meta, content, scan) {
     });
     txn();
 }
+/** Batch-upsert sessions with their FTS5 content and scan stamps in a single transaction. */
 export function upsertSessionsBatch(entries) {
     if (entries.length === 0)
         return;
@@ -330,7 +387,7 @@ export function upsertSessionsBatch(entries) {
             delText.run(meta.id);
             insText.run(meta.id, meta.label ?? '', meta.topic ?? '', meta.project ?? '', content ?? '');
             if (scan && meta.filePath) {
-                ledger.run(meta.filePath, scan.fileMtimeMs, scan.fileSize, now);
+                ledger.run(canonicalLedgerKey(meta.filePath), scan.fileMtimeMs, scan.fileSize, now);
             }
         }
     });
@@ -374,6 +431,7 @@ export function syncLabels(labelMap) {
     txn(updates);
     return updates.length;
 }
+/** Convert a raw database row into a SessionMeta object. */
 function rowToMeta(row) {
     return {
         id: row.id,
@@ -393,6 +451,7 @@ function rowToMeta(row) {
         isTeamOrigin: row.is_team_origin === 1,
     };
 }
+/** Build a parameterized WHERE clause from query options. */
 function buildSessionWhere(options) {
     const where = [];
     const params = [];
@@ -438,6 +497,7 @@ function buildSessionWhere(options) {
     const clause = where.length > 0 ? `WHERE ${where.join(' AND ')}` : '';
     return { clause, params };
 }
+/** Query sessions from the database, applying filters and ordering by timestamp descending. */
 export function querySessions(options = {}) {
     const db = getDB();
     const { clause, params } = buildSessionWhere(options);
@@ -446,6 +506,7 @@ export function querySessions(options = {}) {
     const rows = db.prepare(sql).all(...params);
     return rows.map(rowToMeta);
 }
+/** Count sessions matching the given filter options. */
 export function countSessions(options = {}) {
     const db = getDB();
     const { clause, params } = buildSessionWhere(options);
@@ -453,11 +514,13 @@ export function countSessions(options = {}) {
     const row = db.prepare(sql).get(...params);
     return row ? row.n : 0;
 }
+/** Return the set of all file paths currently tracked in the sessions table. */
 export function getAllFilePaths() {
     const db = getDB();
     const rows = db.prepare(`SELECT file_path FROM sessions`).all();
     return new Set(rows.map(r => r.file_path));
 }
+/** Look up sessions by their source file paths. */
 export function getSessionsByFilePaths(paths) {
     if (paths.length === 0)
         return new Map();
@@ -471,6 +534,7 @@ export function getSessionsByFilePaths(paths) {
         result.set(row.file_path, rowToMeta(row));
     return result;
 }
+/** Look up a single session by its unique ID. */
 export function getSessionById(id) {
     const db = getDB();
     const row = db.prepare(`SELECT * FROM sessions WHERE id = ?`).get(id);
@@ -567,10 +631,10 @@ export function ftsSearch(input, limit = 200) {
     hits.sort((a, b) => b.score - a.score);
     return hits.slice(0, limit);
 }
+/** Return the total row counts for the sessions and FTS5 tables (diagnostic). */
 export function getRowCount() {
     const db = getDB();
     const sessions = db.prepare(`SELECT COUNT(*) AS c FROM sessions`).get().c;
     const textRows = db.prepare(`SELECT COUNT(*) AS c FROM session_text`).get().c;
     return { sessions, textRows };
 }
-//# sourceMappingURL=db.js.map

package/dist/lib/session/discover.d.ts

@@ -1,4 +1,13 @@
+/**
+ * Session discovery across Claude, Codex, Gemini, OpenCode, and OpenClaw.
+ *
+ * Performs incremental scans: each agent's session files are stat'd and compared
+ * to a scan-stamp ledger in SQLite. Only files whose mtime or size changed since
+ * the last run are re-parsed. All metadata is upserted into the sessions DB so
+ * subsequent queries are served entirely from the cache.
+ */
 import type { SessionAgentId, SessionMeta } from './types.js';
+/** Options controlling which sessions to discover and how to report progress. */
 export interface DiscoverOptions {
     agent?: SessionAgentId;
     version?: string;
@@ -19,6 +28,7 @@ export interface DiscoverOptions {
     /** Called as each agent makes parsing progress. Totals count only files that need re-parsing (cache misses). */
     onProgress?: (progress: ScanProgress) => void;
 }
+/** Progress report emitted during incremental scanning. */
 export interface ScanProgress {
     agent: SessionAgentId;
     parsed: number;
@@ -51,10 +61,15 @@ export declare function searchContentIndex(sessions: SessionMeta[], query: strin
  * realpath to avoid double-counting symlinked version homes.
  */
 export declare function getAgentSessionDirs(agent: string, subdir: string): string[];
-export declare function readFirstLines(filePath: string, maxLines: number): Promise<string[]>;
 /**
- * Walk a directory recursively for files with a given extension.
+ * Build a map of Claude sessionId -> user-given label from ~/.claude/sessions/*.json.
+ * Each JSON has shape { pid, sessionId, cwd, startedAt, name?, ... }. The
+ * `name` field only exists if the user ran /rename in that session.
+ * For sessionId collisions (re-resume of the same session), prefer the most
+ * recent startedAt.
  */
-export declare function walkForFiles(dir: string, ext: string, limit: number): string[];
+export declare function buildClaudeLabelMap(): Map<string, string | null>;
+/** Read up to maxLines non-empty lines from the beginning of a file. */
+export declare function readFirstLines(filePath: string, maxLines: number): Promise<string[]>;
+/** Parse a time filter string (relative like '7d' or ISO timestamp) into epoch milliseconds. */
 export declare function parseTimeFilter(input: string): number;
-//# sourceMappingURL=discover.d.ts.map