@phnx-labs/agents-cli 1.20.68 → 1.20.69

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

@@ -0,0 +1,32 @@
+import type { SessionMeta } from './types.js';
+/** Agents that `fork` can branch today (see the module doc for why). */
+export declare const FORKABLE_AGENTS: readonly ["claude"];
+/** Whether a session's agent can be forked by {@link forkSession}. */
+export declare function isForkableAgent(agent: string): boolean;
+/** Outcome of a successful fork. */
+export interface ForkResult {
+    /** The new session's full id. */
+    newId: string;
+    /** The new session's short id (first 8 chars), for display/resume. */
+    shortId: string;
+    /** Absolute path of the copied transcript. */
+    filePath: string;
+    /** The label applied to the fork. */
+    label: string;
+}
+/**
+ * Fork a Claude session into a new, independent one.
+ *
+ * Copies `source.filePath` to a new `<uuid>.jsonl` beside it, rewrites the
+ * embedded session id, registers the new session in the index, and records a
+ * `--name`-style label. Returns the new ids/path. Throws if the source
+ * transcript is missing.
+ *
+ * @param source  The resolved metadata of the session being forked.
+ * @param opts.name  Optional explicit label; defaults to `fork of <original>`.
+ * @param now  ISO timestamp to stamp the fork with (injectable for tests).
+ */
+export declare function forkSession(source: SessionMeta, opts?: {
+    name?: string;
+    now?: string;
+}): ForkResult;

package/dist/lib/session/fork.js

@@ -0,0 +1,101 @@
+/**
+ * Session forking — branch an existing conversation into a new, independent
+ * session that can be continued separately, leaving the original untouched.
+ *
+ * `resume` continues the SAME conversation (same id, same file — it appends).
+ * `fork` copies the transcript under a FRESH session id, so continuing the fork
+ * diverges from the original instead of mutating it. This is the "git branch"
+ * of conversations.
+ *
+ * v1 supports Claude, whose session id IS its `<id>.jsonl` filename and which
+ * resumes natively via `--resume`. A fork is therefore: copy the transcript to
+ * a new-uuid filename in the same directory, rewrite the embedded `sessionId`
+ * on each line, register the new session in the index, and label it. Other
+ * agents (codex single-file; grok/kimi multi-file; opencode DB-only) are a
+ * natural follow-up and are refused up front for now.
+ */
+import { randomUUID } from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+import { upsertSession } from './db.js';
+import { recordRunName } from './run-names.js';
+/** Agents that `fork` can branch today (see the module doc for why). */
+export const FORKABLE_AGENTS = ['claude'];
+/** Whether a session's agent can be forked by {@link forkSession}. */
+export function isForkableAgent(agent) {
+    return FORKABLE_AGENTS.includes(agent);
+}
+/**
+ * Rewrite the per-line `sessionId` field of a Claude JSONL transcript to a new
+ * id. Claude resolves a conversation by its filename, so this is belt-and-braces
+ * (keeps the in-file id consistent with the new filename); malformed lines are
+ * passed through untouched.
+ */
+function rewriteSessionId(transcript, newId) {
+    return transcript
+        .split('\n')
+        .map((line) => {
+        if (!line.trim())
+            return line;
+        try {
+            const obj = JSON.parse(line);
+            if (typeof obj.sessionId === 'string') {
+                obj.sessionId = newId;
+                return JSON.stringify(obj);
+            }
+            return line;
+        }
+        catch {
+            return line;
+        }
+    })
+        .join('\n');
+}
+/**
+ * Fork a Claude session into a new, independent one.
+ *
+ * Copies `source.filePath` to a new `<uuid>.jsonl` beside it, rewrites the
+ * embedded session id, registers the new session in the index, and records a
+ * `--name`-style label. Returns the new ids/path. Throws if the source
+ * transcript is missing.
+ *
+ * @param source  The resolved metadata of the session being forked.
+ * @param opts.name  Optional explicit label; defaults to `fork of <original>`.
+ * @param now  ISO timestamp to stamp the fork with (injectable for tests).
+ */
+export function forkSession(source, opts = {}) {
+    if (!fs.existsSync(source.filePath)) {
+        throw new Error(`transcript not found for session ${source.shortId}: ${source.filePath}`);
+    }
+    const newId = randomUUID();
+    const shortId = newId.slice(0, 8);
+    const dir = path.dirname(source.filePath);
+    const filePath = path.join(dir, `${newId}.jsonl`);
+    const transcript = fs.readFileSync(source.filePath, 'utf-8');
+    const rewritten = rewriteSessionId(transcript, newId);
+    fs.writeFileSync(filePath, rewritten);
+    const original = source.label || source.topic || source.shortId;
+    const label = opts.name || `fork of ${original}`;
+    // Label sidecar (seeds the DB label; survives rescans until an agent title
+    // supersedes it), mirroring `agents run --name`.
+    recordRunName({ sessionId: newId, name: label, agent: source.agent, cwd: source.cwd });
+    // Register the new session so it resolves immediately (by `agents resume`,
+    // `agents sessions`, etc.) without waiting for the next scan.
+    const stamp = opts.now ?? new Date().toISOString();
+    const meta = {
+        ...source,
+        id: newId,
+        shortId,
+        filePath,
+        label,
+        timestamp: stamp,
+        lastActivity: stamp,
+        // The fork has not opened its own PR / team; drop origin-specific refs.
+        prUrl: undefined,
+        prNumber: undefined,
+        teamOrigin: undefined,
+        spawnedTeam: undefined,
+    };
+    upsertSession(meta, rewritten);
+    return { newId, shortId, filePath, label };
+}

package/dist/lib/startup/command-registry.d.ts

@@ -45,6 +45,7 @@ export declare const loadDaemon: ModuleLoader;
 export declare const loadRoutines: ModuleLoader;
 export declare const loadMonitors: ModuleLoader;
 export declare const loadRun: ModuleLoader;
+export declare const loadFork: ModuleLoader;
 export declare const loadDefaults: ModuleLoader;
 export declare const loadModels: ModuleLoader;
 export declare const loadPrune: ModuleLoader;

package/dist/lib/startup/command-registry.js

@@ -23,6 +23,7 @@ export const loadDaemon = async () => (await import('../../commands/daemon.js'))
 export const loadRoutines = async () => (await import('../../commands/routines.js')).registerRoutinesCommands;
 export const loadMonitors = async () => (await import('../../commands/monitors.js')).registerMonitorsCommands;
 export const loadRun = async () => (await import('../../commands/exec.js')).registerRunCommand;
+export const loadFork = async () => (await import('../../commands/fork.js')).registerForkCommand;
 export const loadDefaults = async () => (await import('../../commands/defaults.js')).registerDefaultsCommands;
 export const loadModels = async () => (await import('../../commands/models.js')).registerModelsCommand;
 export const loadPrune = async () => (await import('../../commands/prune.js')).registerPruneCommand;
@@ -126,6 +127,7 @@ export const COMMAND_LOADERS = {
     routines: [loadRoutines],
     monitors: [loadMonitors],
     run: [loadRun],
+    fork: [loadFork],
     defaults: [loadDefaults],
     models: [loadModels],
     trash: [loadTrash],

package/dist/lib/usage.d.ts

@@ -184,6 +184,29 @@ export interface DroidBillingLimitsResponse {
         } | null;
     } | null;
 }
+/**
+ * Live auth probes — the same authenticated GET the usage fetchers above do,
+ * but surfacing the raw HTTP status instead of swallowing 401/expired to null.
+ * These back `agents fleet ping` and the fleet auth-health cache: completing a
+ * real request is the only proof a token is accepted. The local "signed in"
+ * flag cannot tell a revoked-but-unexpired token from a good one. Classification
+ * of the returned status into a verdict lives in lib/auth-health.ts (kept there
+ * so it stays pure/testable and to avoid an import cycle).
+ */
+export interface ProviderProbe {
+    /** HTTP status of the probe request, or null when no request was made (missing/expired token) or the request threw. */
+    status: number | null;
+    /** Local credential state observed before the request. */
+    token: 'present' | 'missing' | 'expired';
+    /** Network/parse error message when status is null but a token was present. */
+    error?: string;
+}
+/** Probe Claude's OAuth token against the usage endpoint. Refreshes an expired access token (safe for Claude). */
+export declare function probeClaudeStatus(home?: string, cliVersion?: string | null): Promise<ProviderProbe>;
+/** Probe Kimi's OAuth token against the /usages endpoint. Never refreshes (single-use rotation — see getKimiUsageInfo). */
+export declare function probeKimiStatus(home?: string): Promise<ProviderProbe>;
+/** Probe Droid's WorkOS token against the billing-limits endpoint. Never refreshes (single-use rotation — see getDroidUsageInfo). */
+export declare function probeDroidStatus(home?: string): Promise<ProviderProbe>;
 /**
  * Normalize the Factory billing-limits payload into the common UsageWindow
  * shape. Orgs on the legacy (non token-rate-limit) billing model have no

package/dist/lib/usage.js

@@ -609,6 +609,90 @@ async function getDroidUsageInfo(options) {
         return { snapshot: null, error: null };
     }
 }
+/** Probe Claude's OAuth token against the usage endpoint. Refreshes an expired access token (safe for Claude). */
+export async function probeClaudeStatus(home, cliVersion) {
+    const oauth = await loadClaudeOauth(home);
+    if (!oauth?.accessToken)
+        return { status: null, token: 'missing' };
+    let access = null;
+    try {
+        access = await getClaudeAccessToken(oauth, home);
+    }
+    catch {
+        access = null;
+    }
+    // Fall back to the stored (possibly stale) token so the server returns the
+    // real verdict — a 401 here IS the revoked/expired signal we want to surface.
+    const bearer = access || oauth.accessToken.trim();
+    try {
+        const response = await fetch(CLAUDE_USAGE_URL, {
+            method: 'GET',
+            headers: {
+                Authorization: `Bearer ${bearer}`,
+                'Content-Type': 'application/json',
+                'anthropic-beta': CLAUDE_OAUTH_BETA_HEADER,
+                'User-Agent': getClaudeUserAgent(cliVersion),
+            },
+            signal: AbortSignal.timeout(8000),
+        });
+        return { status: response.status, token: 'present' };
+    }
+    catch (err) {
+        return { status: null, token: 'present', error: err instanceof Error ? err.message : String(err) };
+    }
+}
+/** Probe Kimi's OAuth token against the /usages endpoint. Never refreshes (single-use rotation — see getKimiUsageInfo). */
+export async function probeKimiStatus(home) {
+    const credPath = resolveKimiCredentialPath(home);
+    if (!credPath)
+        return { status: null, token: 'missing' };
+    let accessToken;
+    let expiresAt = null;
+    try {
+        const cred = JSON.parse(fs.readFileSync(credPath, 'utf-8'));
+        accessToken = typeof cred?.access_token === 'string' ? cred.access_token : undefined;
+        expiresAt = typeof cred?.expires_at === 'number' ? cred.expires_at : null;
+    }
+    catch {
+        return { status: null, token: 'missing' };
+    }
+    if (!accessToken)
+        return { status: null, token: 'missing' };
+    if (expiresAt !== null && Date.now() / 1000 >= expiresAt)
+        return { status: null, token: 'expired' };
+    try {
+        const response = await fetch(KIMI_USAGES_URL, {
+            method: 'GET',
+            headers: { Authorization: `Bearer ${accessToken}`, Accept: 'application/json' },
+            signal: AbortSignal.timeout(8000),
+        });
+        return { status: response.status, token: 'present' };
+    }
+    catch (err) {
+        return { status: null, token: 'present', error: err instanceof Error ? err.message : String(err) };
+    }
+}
+/** Probe Droid's WorkOS token against the billing-limits endpoint. Never refreshes (single-use rotation — see getDroidUsageInfo). */
+export async function probeDroidStatus(home) {
+    const cred = decryptDroidAuthPayload(home || os.homedir());
+    const accessToken = cred?.access_token;
+    if (typeof accessToken !== 'string' || !accessToken)
+        return { status: null, token: 'missing' };
+    const exp = decodeJwtPayload(accessToken)?.exp;
+    if (typeof exp === 'number' && Date.now() / 1000 >= exp)
+        return { status: null, token: 'expired' };
+    try {
+        const response = await fetch(DROID_USAGE_URL, {
+            method: 'GET',
+            headers: { Authorization: `Bearer ${accessToken}`, Accept: 'application/json' },
+            signal: AbortSignal.timeout(8000),
+        });
+        return { status: response.status, token: 'present' };
+    }
+    catch (err) {
+        return { status: null, token: 'present', error: err instanceof Error ? err.message : String(err) };
+    }
+}
 /**
  * Normalize the Factory billing-limits payload into the common UsageWindow
  * shape. Orgs on the legacy (non token-rate-limit) billing model have no

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.68",
+  "version": "1.20.69",
   "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",