@phnx-labs/sessions-cli 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0
+
+- First release. Local FTS search, list, and id lookup against `sessions.db`.
+- Argv fast paths `__query` and `__serve` intercept before commander.
+- FTS input is tokenized the same way as agents-cli, so hyphenated terms like `secrets-cli` no longer crash MATCH as a column name.
+- `__serve` rejects request bodies over 1 MiB.
+- npm pack ships compiled JS only. Push `release/x.y.z` (or `release/x.y.z-pre.n`) to publish.

package/LICENSE

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, Apache 2.0 Future License
+
+## Abbreviation
+
+FSL-1.1-Apache-2.0
+
+## Notice
+
+Copyright 2026 Phoenix Horizon, Inc.
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

package/README.md

@@ -0,0 +1,26 @@
+# sessions
+
+High-performance session index for agents-cli. The installed binary is `sessions`.
+
+It reads the existing SQLite index at `~/.agents/.history/sessions/sessions.db`
+(override with `$SESSIONS_DB`). It does not boot agents-cli, does not fan out
+over SSH, and does not walk transcript directories.
+
+```
+npm i -g @phnx-labs/sessions-cli
+
+sessions "auth middleware" --json --limit 5
+sessions a1b2c3d4 --json
+sessions --limit 20
+```
+
+Hidden fast paths (no commander tree):
+
+```
+sessions __query --json --limit 5 -- auth
+sessions __serve    # request JSON on fd 3, response on fd 4
+```
+
+v1 is the read engine. `resume` / `stop` / `inject` stay on `agents sessions <verb>`.
+
+See PHNX-4012.

package/dist/commands/sessions.d.ts

@@ -0,0 +1,6 @@
+import { Command } from 'commander';
+import { type SessionRow } from '../lib/query.js';
+export declare function printSessions(rows: SessionRow[], json: boolean): void;
+export declare function runQuery(argv: string[]): number;
+export declare function registerSessionsCommands(program: Command): void;
+export declare function buildProgram(): Command;

package/dist/commands/sessions.js

@@ -0,0 +1,69 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { getCliVersion } from '../lib/version.js';
+import { parseQueryArgs, querySessions } from '../lib/query.js';
+function formatRow(row) {
+    const id = chalk.cyan(row.shortId.padEnd(8));
+    const agent = (row.agent || '-').padEnd(8);
+    const version = (row.version || '-').slice(0, 8).padEnd(8);
+    const project = (row.project || '-').slice(0, 16).padEnd(16);
+    const title = (row.label || row.topic || '-').replace(/\s+/g, ' ').slice(0, 40);
+    return `${id}  ${agent} ${version} ${project} ${title}`;
+}
+export function printSessions(rows, json) {
+    if (json) {
+        process.stdout.write(JSON.stringify(rows, null, 2) + '\n');
+        return;
+    }
+    if (rows.length === 0) {
+        process.stderr.write('No sessions matched.\n');
+        return;
+    }
+    for (const row of rows)
+        process.stdout.write(formatRow(row) + '\n');
+    process.stderr.write(`${rows.length} session${rows.length === 1 ? '' : 's'}.\n`);
+}
+export function runQuery(argv) {
+    const json = argv.includes('--json');
+    const options = parseQueryArgs(argv);
+    try {
+        const rows = querySessions(options);
+        printSessions(rows, json);
+        return 0;
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+}
+export function registerSessionsCommands(program) {
+    program
+        .argument('[query...]', 'FTS query, or a session id')
+        .option('--json', 'JSON array of SessionMeta-shaped rows')
+        .option('--limit <n>', 'max rows', '20')
+        .option('--agent <id>', 'filter by harness (claude, grok, …)')
+        .option('--local', 'local index only (always true in v1; accepted for agents-cli flag parity)')
+        .option('--no-interactive', 'ignored; this CLI never opens a picker')
+        .allowExcessArguments()
+        .allowUnknownOption()
+        .action(() => {
+        process.exit(runQuery(process.argv.slice(2)));
+    });
+    program.addHelpText('after', `
+Examples:
+  sessions "auth middleware" --json --limit 5
+  sessions a1b2c3d4 --json
+  sessions --limit 20
+
+v1 is the read/index engine. resume/stop/inject stay on \`agents sessions <verb>\`.
+Hidden fast paths (no commander): __query  __serve
+`);
+}
+export function buildProgram() {
+    const program = new Command('sessions')
+        .description('Search and list indexed agent sessions. Local, no SSH, no agents-cli boot.')
+        .version(getCliVersion(), '-v, --version')
+        .showHelpAfterError();
+    registerSessionsCommands(program);
+    return program;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env -S node --no-warnings=ExperimentalWarning
+export {};

package/dist/index.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env -S node --no-warnings=ExperimentalWarning
+/**
+ * `sessions` — standalone session index CLI (PHNX-4012).
+ *
+ * Hidden entrypoints are intercepted BEFORE commander so they never pay for
+ * command-tree construction:
+ *
+ *   - `__query`  FTS / list / id lookup, JSON or text, then exit
+ *   - `__serve`  private consumer pipe: request on fd 3, response on fd 4
+ */
+import { getCliVersion } from './lib/version.js';
+process.on('SIGPIPE', () => { });
+const verb = process.argv[2];
+if (verb === '__serve') {
+    const { runProtocolServer } = await import('./protocol-server.js');
+    runProtocolServer();
+    process.exit(process.exitCode ?? 0);
+}
+if (verb === '__query') {
+    const { runQuery } = await import('./commands/sessions.js');
+    process.exit(runQuery(process.argv.slice(3)));
+}
+if (verb === '--version' || verb === '-v') {
+    process.stdout.write(getCliVersion() + '\n');
+    process.exit(0);
+}
+const { buildProgram } = await import('./commands/sessions.js');
+const program = buildProgram();
+try {
+    await program.parseAsync(process.argv);
+}
+catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(1);
+}

package/dist/lib/paths.d.ts

@@ -0,0 +1,7 @@
+/** Default index path — the same file agents-cli already writes. */
+export declare function defaultSessionsDbPath(home?: string): string;
+/**
+ * Resolve the SQLite index. `$SESSIONS_DB` wins (tests, power users),
+ * then `$AGENTS_SESSIONS_DB` (the agents-cli test seam), else the default.
+ */
+export declare function resolveSessionsDbPath(env?: NodeJS.ProcessEnv, home?: string): string;

package/dist/lib/paths.js

@@ -0,0 +1,16 @@
+import * as os from 'os';
+import * as path from 'path';
+/** Default index path — the same file agents-cli already writes. */
+export function defaultSessionsDbPath(home = os.homedir()) {
+    return path.join(home, '.agents', '.history', 'sessions', 'sessions.db');
+}
+/**
+ * Resolve the SQLite index. `$SESSIONS_DB` wins (tests, power users),
+ * then `$AGENTS_SESSIONS_DB` (the agents-cli test seam), else the default.
+ */
+export function resolveSessionsDbPath(env = process.env, home = os.homedir()) {
+    const explicit = env.SESSIONS_DB?.trim() || env.AGENTS_SESSIONS_DB?.trim();
+    if (explicit)
+        return explicit;
+    return defaultSessionsDbPath(home);
+}

package/dist/lib/query.d.ts

@@ -0,0 +1,47 @@
+import { DatabaseSync } from 'node:sqlite';
+export interface SessionRow {
+    id: string;
+    shortId: string;
+    agent: string;
+    version: string | null;
+    account: string | null;
+    timestamp: string;
+    lastActivity: string | null;
+    project: string | null;
+    cwd: string | null;
+    gitBranch: string | null;
+    topic: string | null;
+    label: string | null;
+    messageCount: number | null;
+    tokenCount: number | null;
+    filePath: string;
+    origin: string | null;
+    machine: string | null;
+    model: string | null;
+    harness: string | null;
+    ticketId: string | null;
+    prUrl: string | null;
+    durationMs: number | null;
+    costUsd: number | null;
+}
+export interface QueryOptions {
+    query?: string;
+    limit?: number;
+    idPrefix?: string;
+    agent?: string;
+    dbPath?: string;
+}
+/**
+ * Turn a raw user query into a safe FTS5 MATCH expression.
+ * Same tokenizer as agents-cli: split on non-alphanumeric, keep tokens of
+ * 2+ chars, prefix-match with OR. Hyphens, colons, and FTS operators never
+ * reach MATCH as syntax — `secrets-cli` cannot throw `no such column: cli`.
+ */
+export declare function buildFtsQuery(input: string): {
+    expr: string;
+    terms: string[];
+};
+export declare function openSessionsDb(dbPath?: string): DatabaseSync;
+export declare function querySessions(options?: QueryOptions): SessionRow[];
+export declare function looksLikeId(value: string): boolean;
+export declare function parseQueryArgs(argv: string[]): QueryOptions;

package/dist/lib/query.js

@@ -0,0 +1,156 @@
+/**
+ * Read-only session index. Opens sessions.db, runs FTS / listing / id lookup,
+ * never walks the filesystem, never writes, never talks to SSH.
+ *
+ * Column names match agents-cli SessionMeta JSON so `agents sessions --json`
+ * consumers keep working after the passthrough cutover.
+ */
+import * as fs from 'fs';
+import { DatabaseSync } from 'node:sqlite';
+import { resolveSessionsDbPath } from './paths.js';
+const SELECT_COLS = `
+  s.id,
+  s.short_id AS shortId,
+  s.agent,
+  s.version,
+  s.account,
+  s.timestamp,
+  s.last_activity AS lastActivity,
+  s.project,
+  s.cwd,
+  s.git_branch AS gitBranch,
+  s.topic,
+  s.label,
+  s.message_count AS messageCount,
+  s.token_count AS tokenCount,
+  s.file_path AS filePath,
+  s.origin,
+  s.machine,
+  s.model,
+  s.harness,
+  s.ticket_id AS ticketId,
+  s.pr_url AS prUrl,
+  s.duration_ms AS durationMs,
+  s.cost_usd AS costUsd
+`;
+/**
+ * Turn a raw user query into a safe FTS5 MATCH expression.
+ * Same tokenizer as agents-cli: split on non-alphanumeric, keep tokens of
+ * 2+ chars, prefix-match with OR. Hyphens, colons, and FTS operators never
+ * reach MATCH as syntax — `secrets-cli` cannot throw `no such column: cli`.
+ */
+export function buildFtsQuery(input) {
+    const terms = input.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length >= 2);
+    if (terms.length === 0)
+        return { expr: '', terms: [] };
+    return { expr: terms.map((t) => `${t}*`).join(' OR '), terms };
+}
+export function openSessionsDb(dbPath = resolveSessionsDbPath()) {
+    return new DatabaseSync(dbPath, { readOnly: true });
+}
+function rowFrom(raw) {
+    return {
+        id: String(raw.id),
+        shortId: String(raw.shortId ?? ''),
+        agent: String(raw.agent ?? ''),
+        version: raw.version ?? null,
+        account: raw.account ?? null,
+        timestamp: String(raw.timestamp ?? ''),
+        lastActivity: raw.lastActivity ?? null,
+        project: raw.project ?? null,
+        cwd: raw.cwd ?? null,
+        gitBranch: raw.gitBranch ?? null,
+        topic: raw.topic ?? null,
+        label: raw.label ?? null,
+        messageCount: typeof raw.messageCount === 'number' ? raw.messageCount : null,
+        tokenCount: typeof raw.tokenCount === 'number' ? raw.tokenCount : null,
+        filePath: String(raw.filePath ?? ''),
+        origin: raw.origin ?? null,
+        machine: raw.machine ?? null,
+        model: raw.model ?? null,
+        harness: raw.harness ?? null,
+        ticketId: raw.ticketId ?? null,
+        prUrl: raw.prUrl ?? null,
+        durationMs: typeof raw.durationMs === 'number' ? raw.durationMs : null,
+        costUsd: typeof raw.costUsd === 'number' ? raw.costUsd : null,
+    };
+}
+export function querySessions(options = {}) {
+    const dbPath = options.dbPath ?? resolveSessionsDbPath();
+    const limit = Math.max(1, Math.min(options.limit ?? 20, 500));
+    if (!fs.existsSync(dbPath) || fs.statSync(dbPath).size === 0)
+        return [];
+    const db = openSessionsDb(dbPath);
+    try {
+        if (options.idPrefix && looksLikeId(options.idPrefix) && !options.query) {
+            const stmt = db.prepare(`SELECT ${SELECT_COLS} FROM sessions s
+         WHERE (s.id = ? OR s.id LIKE ? OR s.short_id = ?)
+           AND s.archived_at IS NULL
+         LIMIT ?`);
+            const prefix = options.idPrefix;
+            const rows = stmt.all(prefix, `${prefix}%`, prefix, limit);
+            return rows.map(rowFrom);
+        }
+        if (options.query && options.query.trim()) {
+            const { expr } = buildFtsQuery(options.query);
+            if (!expr)
+                return [];
+            const stmt = db.prepare(`SELECT ${SELECT_COLS}
+         FROM sessions s
+         JOIN session_text t ON t.session_id = s.id
+         WHERE session_text MATCH ?
+           AND s.archived_at IS NULL
+           ${options.agent ? 'AND s.agent = ?' : ''}
+         ORDER BY rank
+         LIMIT ?`);
+            const bind = options.agent ? [expr, options.agent, limit] : [expr, limit];
+            const rows = stmt.all(...bind);
+            return rows.map(rowFrom);
+        }
+        const stmt = db.prepare(`SELECT ${SELECT_COLS} FROM sessions s
+       WHERE s.archived_at IS NULL
+         ${options.agent ? 'AND s.agent = ?' : ''}
+       ORDER BY s.last_activity DESC, s.timestamp DESC
+       LIMIT ?`);
+        const bind = options.agent ? [options.agent, limit] : [limit];
+        const rows = stmt.all(...bind);
+        return rows.map(rowFrom);
+    }
+    finally {
+        db.close();
+    }
+}
+export function looksLikeId(value) {
+    return /^[0-9a-f]{8,}$/i.test(value) || /^[0-9a-f-]{8,}$/i.test(value);
+}
+export function parseQueryArgs(argv) {
+    const options = {};
+    const rest = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--json' || arg === '--local' || arg === '--no-interactive')
+            continue;
+        if (arg === '--limit' && argv[i + 1]) {
+            options.limit = Number(argv[++i]);
+            continue;
+        }
+        if (arg.startsWith('--limit=')) {
+            options.limit = Number(arg.slice('--limit='.length));
+            continue;
+        }
+        if (arg === '--agent' && argv[i + 1]) {
+            options.agent = argv[++i];
+            continue;
+        }
+        if (arg.startsWith('--'))
+            continue;
+        rest.push(arg);
+    }
+    if (rest.length === 1 && looksLikeId(rest[0]) && !rest[0].includes(' ')) {
+        options.idPrefix = rest[0];
+    }
+    else if (rest.length > 0) {
+        options.query = rest.join(' ');
+    }
+    return options;
+}

package/dist/lib/version.d.ts

@@ -0,0 +1 @@
+export declare function getCliVersion(pkgJsonPath?: string): string;

package/dist/lib/version.js

@@ -0,0 +1,18 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PKG_JSON = path.join(__dirname, '..', '..', 'package.json');
+let cached = null;
+export function getCliVersion(pkgJsonPath = PKG_JSON) {
+    if (cached)
+        return cached;
+    try {
+        const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
+        cached = String(pkg.version || '') || 'unknown';
+    }
+    catch {
+        cached = 'unknown';
+    }
+    return cached;
+}

package/dist/protocol-server.d.ts

@@ -0,0 +1,4 @@
+/** Cap the __serve request body. Local caller, but unbounded read is a DoS. */
+export declare const MAX_REQUEST_BYTES: number;
+export declare function readFd(fd: number, maxBytes?: number): Buffer;
+export declare function runProtocolServer(): void;

package/dist/protocol-server.js

@@ -0,0 +1,69 @@
+import * as fs from 'fs';
+import { PROTOCOL_VERSION } from './protocol.js';
+import { querySessions } from './lib/query.js';
+/** Cap the __serve request body. Local caller, but unbounded read is a DoS. */
+export const MAX_REQUEST_BYTES = 1024 * 1024;
+export function readFd(fd, maxBytes = MAX_REQUEST_BYTES) {
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const buf = Buffer.alloc(64 * 1024);
+        const n = fs.readSync(fd, buf, 0, buf.length, null);
+        if (n === 0)
+            break;
+        total += n;
+        if (total > maxBytes) {
+            throw new Error(`request exceeds ${maxBytes} bytes`);
+        }
+        chunks.push(buf.subarray(0, n));
+    }
+    return Buffer.concat(chunks);
+}
+export function runProtocolServer() {
+    let raw;
+    try {
+        raw = readFd(3);
+    }
+    catch (error) {
+        process.stderr.write(`sessions __serve: failed to read fd 3: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exit(1);
+        return;
+    }
+    let request;
+    try {
+        request = JSON.parse(raw.toString('utf8'));
+    }
+    catch {
+        writeResponse({
+            v: PROTOCOL_VERSION,
+            id: '',
+            ok: false,
+            error: { code: 'INVALID_RESPONSE', message: 'request is not JSON' },
+        });
+        return;
+    }
+    try {
+        const rows = querySessions({
+            query: request.op === 'get' ? undefined : request.args?.query,
+            idPrefix: request.op === 'get' ? request.args?.idPrefix : request.args?.idPrefix,
+            limit: request.args?.limit,
+            agent: request.args?.agent,
+        });
+        writeResponse({ v: PROTOCOL_VERSION, id: request.id, ok: true, result: rows });
+    }
+    catch (error) {
+        writeResponse({
+            v: PROTOCOL_VERSION,
+            id: request.id,
+            ok: false,
+            error: {
+                code: 'OPERATION_FAILED',
+                message: error instanceof Error ? error.message : String(error),
+            },
+        });
+    }
+}
+function writeResponse(response) {
+    const body = Buffer.from(JSON.stringify(response), 'utf8');
+    fs.writeSync(4, body);
+}

package/dist/protocol.d.ts

@@ -0,0 +1,23 @@
+export declare const PROTOCOL_VERSION = 1;
+export type SessionsOp = 'query' | 'list' | 'get';
+export interface SessionsRequest {
+    v: number;
+    id: string;
+    op: SessionsOp;
+    args: {
+        query?: string;
+        limit?: number;
+        idPrefix?: string;
+        agent?: string;
+    };
+}
+export interface SessionsResponse {
+    v: number;
+    id: string;
+    ok: boolean;
+    result?: unknown;
+    error?: {
+        code: string;
+        message: string;
+    };
+}

package/dist/protocol.js

@@ -0,0 +1 @@
+export const PROTOCOL_VERSION = 1;

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@phnx-labs/sessions-cli",
+  "version": "0.1.0",
+  "description": "High-performance session index: search, list, and preview agent transcripts",
+  "type": "module",
+  "bin": {
+    "sessions": "dist/index.js"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/phnx-labs/sessions-cli.git"
+  },
+  "license": "FSL-1.1-Apache-2.0",
+  "scripts": {
+    "build": "bash scripts/build.sh",
+    "test": "bash scripts/test.sh",
+    "scan": "bash scripts/scan.sh",
+    "release": "bash scripts/release.sh"
+  },
+  "dependencies": {
+    "commander": "15.0.0",
+    "chalk": "5.6.2"
+  },
+  "devDependencies": {
+    "@types/node": "26.1.0",
+    "tsx": "4.21.0",
+    "typescript": "6.0.3",
+    "vitest": "4.1.9"
+  }
+}