@phnx-labs/agents-cli 1.20.72 → 1.20.74

package/dist/lib/exec.d.ts

@@ -158,6 +158,17 @@ export interface ExecOptions {
  * `--interactive` takes precedence over `--headless`; the CLI layer rejects passing both.
  */
 export declare function resolveInteractive(options: Pick<ExecOptions, 'interactive' | 'headless' | 'prompt'>): boolean;
+/**
+ * True when a run resolved to *inferred* interactive intent — no prompt and no
+ * explicit `--interactive` — but there is no terminal to host the REPL. Launching
+ * would attach a TUI to a dead stdin and hang forever, so the caller should fail
+ * fast with the headless alternatives instead (RUSH-1829).
+ *
+ * An explicit `--interactive` is the caller's deliberate choice and is never
+ * blocked (they may be driving a PTY we can't detect). Pure — the TTY state is a
+ * parameter so this is unit-testable without touching `process.std*`.
+ */
+export declare function inferredInteractiveWithoutTty(options: Pick<ExecOptions, 'interactive' | 'headless' | 'prompt'>, isTty: boolean): boolean;
 /**
  * Decide whether spawnAgent must capture (PIPE + tee) the child's stdout so the
  * live budget watcher can parse it (issue #346, FIX 3).

package/dist/lib/exec.js

@@ -15,7 +15,8 @@ import { getBinaryPath, getVersionHomePath, isVersionInstalled, resolveVersion }
 import { resolveModel, buildReasoningFlags } from './models.js';
 import { maybeRotate, createTimer, redactPrompt, redactArgs } from './events.js';
 import { sanitizeProcessEnv } from './secrets/bundles.js';
-import { getShimsDir } from './state.js';
+import { getShimsDir, getHistoryDir } from './state.js';
+import { resolveCodexHome } from './codex-home.js';
 import { readCodexConfiguredModel } from './shims.js';
 import { writePidSessionEntry, extractSessionIdArg } from './session/pid-registry.js';
 import { recordRunName } from './session/run-names.js';
@@ -153,6 +154,21 @@ export function resolveInteractive(options) {
         return false;
     return options.prompt === undefined;
 }
+/**
+ * True when a run resolved to *inferred* interactive intent — no prompt and no
+ * explicit `--interactive` — but there is no terminal to host the REPL. Launching
+ * would attach a TUI to a dead stdin and hang forever, so the caller should fail
+ * fast with the headless alternatives instead (RUSH-1829).
+ *
+ * An explicit `--interactive` is the caller's deliberate choice and is never
+ * blocked (they may be driving a PTY we can't detect). Pure — the TTY state is a
+ * parameter so this is unit-testable without touching `process.std*`.
+ */
+export function inferredInteractiveWithoutTty(options, isTty) {
+    if (options.interactive === true)
+        return false;
+    return resolveInteractive(options) && !isTty;
+}
 /**
  * Decide whether spawnAgent must capture (PIPE + tee) the child's stdout so the
  * live budget watcher can parse it (issue #346, FIX 3).
@@ -241,7 +257,12 @@ export function buildExecEnv(options) {
             ? resolvedVersion
             : (resolvedVersion && isVersionInstalled('codex', resolvedVersion) ? resolvedVersion : null);
         if (version) {
-            result.CODEX_HOME = path.join(getVersionHomePath('codex', version), '.codex');
+            // On macOS the deep versioned home overflows the Unix-socket SUN_LEN
+            // limit for codex's app-server control socket; resolve to a short,
+            // SUN_LEN-safe home (migrating once if needed). See codex-home.ts.
+            const versionedHome = path.join(getVersionHomePath('codex', version), '.codex');
+            const agentsUserDir = path.dirname(getHistoryDir());
+            result.CODEX_HOME = resolveCodexHome(versionedHome, agentsUserDir, version);
         }
         delete result.CLAUDE_CONFIG_DIR;
         delete result.COPILOT_HOME;

package/dist/lib/export.d.ts

@@ -0,0 +1,72 @@
+import type { AgentId } from './types.js';
+export type ExportMode = 'merge' | 'replace' | 'staged';
+/** Filename of the provenance receipt written into the agent's config dir. */
+export declare const RECEIPT_NAME = ".agents-cli-export.json";
+/** Suffix for the incoming copy of a file the user already has. */
+export declare const CONFLICT_SUFFIX = ".from-agents-cli";
+/** Why an export cannot proceed. Each maps to a distinct user-facing remedy. */
+export type ExportBlocker = {
+    kind: 'not-installed';
+} | {
+    kind: 'not-isolated';
+} | {
+    kind: 'no-config';
+    source: string;
+} | {
+    kind: 'dest-adopted';
+    realPath: string;
+    adoptedVersion: string;
+};
+/** What the destination `~/.<agent>` currently is. */
+export type DestKind = 'absent' | 'real-dir' | 'foreign-symlink';
+/** One file the export would place, relative to the config dir root. */
+export interface ExportEntry {
+    /** Path relative to the config dir, e.g. `prompts/review.md`. */
+    rel: string;
+    /** Absolute source file inside the isolated home. */
+    source: string;
+    /** Absolute path this file will be written to. */
+    target: string;
+    /**
+     * Set when the user already has `rel`. `target` then points at the
+     * `.from-agents-cli` sibling, and `existing` is the untouched original.
+     */
+    existing?: string;
+}
+export interface ExportPlan {
+    agent: AgentId;
+    version: string;
+    mode: ExportMode;
+    /** The isolated config dir, e.g. `<versionDir>/home/.codex`. */
+    source: string;
+    /** The user's real config dir, e.g. `~/.codex`. */
+    dest: string;
+    destKind: DestKind;
+    /** Files with no counterpart in `dest` — written in place. */
+    writes: ExportEntry[];
+    /** Files the user already has — written alongside, never over. */
+    conflicts: ExportEntry[];
+    /** replace mode only: where `dest` gets moved first. */
+    backupPath: string | null;
+    /** staged mode only: the subdirectory receiving the whole tree. */
+    stagedPath: string | null;
+    receiptPath: string;
+    blocker: ExportBlocker | null;
+}
+export interface ExportResult {
+    exported: boolean;
+    dest: string;
+    written: string[];
+    conflicts: Array<{
+        path: string;
+        theirs: string;
+    }>;
+    backupPath: string | null;
+    stagedPath: string | null;
+    receiptPath: string | null;
+    errors: string[];
+}
+/** Build a read-only plan. Performs no mutations. */
+export declare function planExport(agent: AgentId, version: string, timestamp: number, mode?: ExportMode): ExportPlan;
+/** Execute a plan from {@link planExport}. */
+export declare function executeExport(plan: ExportPlan, timestamp: number): ExportResult;

package/dist/lib/export.js

@@ -0,0 +1,269 @@
+/**
+ * `agents export` — copy an ISOLATED install's config back out to the user's real
+ * `~/.<agent>`, so they can keep their settings and delete agents-cli entirely.
+ *
+ * Isolation is currently a one-way door: `agents add <agent>@<v> --isolated` builds a
+ * self-contained home under the version dir, and nothing ever brings that work back.
+ * Reversibility is what makes a sandbox safe to try.
+ *
+ * Three modes, because "export" means different things depending on which config you
+ * consider authoritative:
+ *
+ *   merge (default) — additive. Copy only paths the user doesn't already have. A
+ *                     collision is NOT silently skipped: the incoming file is written
+ *                     beside theirs as `<name>.from-agents-cli` so they can diff and
+ *                     take the parts they want. Nothing of theirs is ever modified.
+ *   replace         — the isolated config becomes `~/.<agent>`; theirs moves to
+ *                     `backups/<agent>/<ts>`. For when you've been living in the
+ *                     sandbox and want to promote it wholesale.
+ *   staged          — write the whole tree to `~/.<agent>/.agents-export-<ts>/` and
+ *                     activate nothing. For inspecting first.
+ *
+ * Every mode leaves a receipt at `~/.<agent>/.agents-cli-export.json` recording what
+ * came from the export. That is what makes provenance answerable ("which of these
+ * files are mine?") and the whole operation reversible.
+ *
+ * Deliberately NOT implemented: key-level merging of file *contents*. The TOML
+ * library here does not preserve comments across parse+stringify, so auto-merging a
+ * `config.toml` would silently delete the user's comments. Handing over both files
+ * and a diff is honest; rewriting their config behind a "merge" flag is not.
+ *
+ * Split into a read-only {@link planExport} and a mutating {@link executeExport} so
+ * `--dry-run` and the real run share one code path, mirroring `lib/uninstall.ts`.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { AGENTS } from './agents.js';
+import { getAgentConfigPath, getConfigSymlinkVersion } from './shims.js';
+import { getVersionHomePath, isVersionIsolated, isVersionInstalled } from './versions.js';
+import { getUserAgentsDir, getBackupsDir } from './state.js';
+import { copyDirStrippingAgentsSymlinks, moveDirCrossDevice } from './config-transfer.js';
+/** Filename of the provenance receipt written into the agent's config dir. */
+export const RECEIPT_NAME = '.agents-cli-export.json';
+/** Suffix for the incoming copy of a file the user already has. */
+export const CONFLICT_SUFFIX = '.from-agents-cli';
+/** The config dir's basename (`.codex`), used to locate it inside a version home. */
+function configBasename(agent) {
+    return path.basename(AGENTS[agent].configDir);
+}
+/**
+ * Every regular file under `root`, as paths relative to it. Symlinks pointing back
+ * into `~/.agents` are omitted for the same reason `copyDirStrippingAgentsSymlinks`
+ * drops them: they dangle the moment `~/.agents` is disposed, and an export that
+ * leaves dangling links is not an export.
+ */
+function walkFiles(root, agentsDir, rel = '') {
+    const inside = agentsDir + path.sep;
+    const out = [];
+    let entries;
+    try {
+        entries = fs.readdirSync(path.join(root, rel), { withFileTypes: true });
+    }
+    catch {
+        return out;
+    }
+    for (const entry of entries) {
+        const childRel = rel ? path.join(rel, entry.name) : entry.name;
+        const abs = path.join(root, childRel);
+        if (entry.isSymbolicLink()) {
+            try {
+                const tgt = path.resolve(path.dirname(abs), fs.readlinkSync(abs));
+                if (tgt === agentsDir || tgt.startsWith(inside))
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            out.push(childRel);
+            continue;
+        }
+        if (entry.isDirectory()) {
+            out.push(...walkFiles(root, agentsDir, childRel));
+            continue;
+        }
+        out.push(childRel);
+    }
+    return out;
+}
+/** Build a read-only plan. Performs no mutations. */
+export function planExport(agent, version, timestamp, mode = 'merge') {
+    const source = path.join(getVersionHomePath(agent, version), configBasename(agent));
+    const dest = getAgentConfigPath(agent);
+    const base = {
+        agent,
+        version,
+        mode,
+        source,
+        dest,
+        destKind: 'absent',
+        writes: [],
+        conflicts: [],
+        backupPath: null,
+        stagedPath: null,
+        receiptPath: path.join(dest, RECEIPT_NAME),
+    };
+    if (!isVersionInstalled(agent, version))
+        return { ...base, blocker: { kind: 'not-installed' } };
+    if (!isVersionIsolated(agent, version))
+        return { ...base, blocker: { kind: 'not-isolated' } };
+    if (!fs.existsSync(source))
+        return { ...base, blocker: { kind: 'no-config', source } };
+    // Refuse when `~/.<agent>` is a symlink agents-cli owns: the agent has a normal
+    // install that adopted it, so writing there would land inside a version home
+    // rather than in the user's real config, and silently mutate that other install.
+    const adopted = getConfigSymlinkVersion(agent);
+    if (adopted !== null) {
+        return { ...base, blocker: { kind: 'dest-adopted', realPath: dest, adoptedVersion: adopted } };
+    }
+    let destKind = 'absent';
+    try {
+        destKind = fs.lstatSync(dest).isSymbolicLink() ? 'foreign-symlink' : 'real-dir';
+    }
+    catch {
+        destKind = 'absent';
+    }
+    const agentsDir = getUserAgentsDir();
+    const rels = walkFiles(source, agentsDir).sort();
+    if (mode === 'staged') {
+        const stagedPath = path.join(dest, `.agents-export-${timestamp}`);
+        return {
+            ...base,
+            destKind,
+            stagedPath,
+            writes: rels.map((rel) => ({
+                rel,
+                source: path.join(source, rel),
+                target: path.join(stagedPath, rel),
+            })),
+            blocker: null,
+        };
+    }
+    if (mode === 'replace') {
+        return {
+            ...base,
+            destKind,
+            backupPath: destKind === 'real-dir' ? path.join(getBackupsDir(), agent, String(timestamp)) : null,
+            writes: rels.map((rel) => ({
+                rel,
+                source: path.join(source, rel),
+                target: path.join(dest, rel),
+            })),
+            blocker: null,
+        };
+    }
+    // merge: additive. Anything the user already has becomes a conflict written
+    // alongside, so their file is never the thing that changes.
+    const writes = [];
+    const conflicts = [];
+    for (const rel of rels) {
+        const target = path.join(dest, rel);
+        let exists = false;
+        try {
+            fs.lstatSync(target);
+            exists = true;
+        }
+        catch {
+            exists = false;
+        }
+        if (exists) {
+            conflicts.push({
+                rel,
+                source: path.join(source, rel),
+                target: target + CONFLICT_SUFFIX,
+                existing: target,
+            });
+        }
+        else {
+            writes.push({ rel, source: path.join(source, rel), target });
+        }
+    }
+    return { ...base, destKind, writes, conflicts, blocker: null };
+}
+/** Copy one file, creating parent dirs. Symlinks are recreated, not followed. */
+function placeFile(entry) {
+    fs.mkdirSync(path.dirname(entry.target), { recursive: true });
+    const st = fs.lstatSync(entry.source);
+    if (st.isSymbolicLink()) {
+        const link = fs.readlinkSync(entry.source);
+        try {
+            fs.unlinkSync(entry.target);
+        }
+        catch {
+            /* nothing there */
+        }
+        fs.symlinkSync(link, entry.target);
+        return;
+    }
+    fs.copyFileSync(entry.source, entry.target);
+}
+function writeReceipt(plan, result, timestamp) {
+    const receipt = {
+        exportedAt: new Date(timestamp).toISOString(),
+        from: `${plan.agent}@${plan.version} (isolated)`,
+        mode: plan.mode,
+        written: result.written,
+        conflicts: result.conflicts,
+        ...(result.backupPath ? { backupPath: result.backupPath } : {}),
+        ...(result.stagedPath ? { stagedAt: result.stagedPath } : {}),
+        note: plan.mode === 'merge'
+            ? `Files under "written" came from this export. Paths under "conflicts" already existed and were NOT modified — the incoming version sits beside yours with the ${CONFLICT_SUFFIX} suffix.`
+            : plan.mode === 'replace'
+                ? 'This config was replaced wholesale by the export; the previous one is at backupPath.'
+                : 'Nothing was activated — the exported tree sits under stagedAt.',
+    };
+    fs.mkdirSync(path.dirname(plan.receiptPath), { recursive: true });
+    fs.writeFileSync(plan.receiptPath, JSON.stringify(receipt, null, 2) + '\n');
+}
+/** Execute a plan from {@link planExport}. */
+export function executeExport(plan, timestamp) {
+    const result = {
+        exported: false,
+        dest: plan.dest,
+        written: [],
+        conflicts: [],
+        backupPath: null,
+        stagedPath: null,
+        receiptPath: null,
+        errors: [],
+    };
+    if (plan.blocker) {
+        result.errors.push(`refusing to export: ${plan.blocker.kind}`);
+        return result;
+    }
+    try {
+        if (plan.mode === 'replace') {
+            if (plan.backupPath) {
+                fs.mkdirSync(path.dirname(plan.backupPath), { recursive: true });
+                moveDirCrossDevice(plan.dest, plan.backupPath);
+                result.backupPath = plan.backupPath;
+            }
+            else if (plan.destKind === 'foreign-symlink') {
+                // Not ours to back up, but it must go or cpSync would write through it.
+                fs.unlinkSync(plan.dest);
+            }
+            copyDirStrippingAgentsSymlinks(plan.source, plan.dest, getUserAgentsDir());
+            result.written = plan.writes.map((w) => w.rel);
+        }
+        else {
+            // merge and staged both place individual files; neither disturbs anything
+            // the user already has.
+            for (const entry of plan.writes) {
+                placeFile(entry);
+                result.written.push(entry.rel);
+            }
+            for (const entry of plan.conflicts) {
+                placeFile(entry);
+                result.conflicts.push({ path: entry.rel, theirs: entry.target });
+            }
+            if (plan.stagedPath)
+                result.stagedPath = plan.stagedPath;
+        }
+        writeReceipt(plan, result, timestamp);
+        result.receiptPath = plan.receiptPath;
+        result.exported = true;
+    }
+    catch (err) {
+        result.errors.push(err instanceof Error ? err.message : String(err));
+    }
+    return result;
+}

package/dist/lib/feed-policy.d.ts

@@ -27,4 +27,4 @@ export interface PolicyResult {
  * Apply policy to a single open block. Returns the action taken (none/defaulted/parked).
  * Caller is responsible for persistence/logging side effects not owned by feed.ts.
  */
-export declare function applyPolicyToBlock(block: OpenBlock, policy: FeedPolicy, now: Date, root?: string): PolicyResult;
+export declare function applyPolicyToBlock(block: OpenBlock, policy: FeedPolicy, now: Date, root?: string, mailboxRoot?: string): PolicyResult;

package/dist/lib/feed-policy.js

@@ -28,12 +28,12 @@ export const DEFAULT_POLICY = {
 export function getPolicyPath(root) {
     return path.join(root ?? getUserAgentsDir(), POLICY_FILE);
 }
-function normalizeClassPolicy(raw) {
+function normalizeClassPolicy(raw, fallback) {
     const p = (raw ?? {});
-    const timeout = typeof p.timeoutMinutes === 'number' ? p.timeoutMinutes : DEFAULT_POLICY.approval.timeoutMinutes;
+    const timeout = typeof p.timeoutMinutes === 'number' ? p.timeoutMinutes : fallback.timeoutMinutes;
     return {
         timeoutMinutes: Math.max(1, Math.round(timeout)),
-        safeDefault: typeof p.safeDefault === 'string' ? p.safeDefault : undefined,
+        safeDefault: typeof p.safeDefault === 'string' ? p.safeDefault : fallback.safeDefault,
     };
 }
 export function loadPolicy(root) {
@@ -45,8 +45,8 @@ export function loadPolicy(root) {
             const p = parsed;
             const threshold = p.phoneNotifyThreshold;
             return {
-                approval: normalizeClassPolicy(p.approval ?? { timeoutMinutes: DEFAULT_POLICY.approval.timeoutMinutes, safeDefault: DEFAULT_POLICY.approval.safeDefault }),
-                decision: normalizeClassPolicy(p.decision ?? { timeoutMinutes: DEFAULT_POLICY.decision.timeoutMinutes }),
+                approval: normalizeClassPolicy(p.approval, DEFAULT_POLICY.approval),
+                decision: normalizeClassPolicy(p.decision, DEFAULT_POLICY.decision),
                 phoneNotifyThreshold: threshold === 'low' || threshold === 'medium' || threshold === 'high' ? threshold : DEFAULT_POLICY.phoneNotifyThreshold,
             };
         }
@@ -71,16 +71,21 @@ export function minutesElapsed(block, now) {
         return 0;
     return (now.getTime() - ts) / 60_000;
 }
+function timeoutMinutesForBlock(block, policy) {
+    if (typeof block.timeoutMinutes === 'number' && Number.isFinite(block.timeoutMinutes) && block.timeoutMinutes > 0) {
+        return Math.max(1, Math.round(block.timeoutMinutes));
+    }
+    return policy[blockClass(block)].timeoutMinutes;
+}
 export function isTimedOut(block, policy, now) {
-    const cls = blockClass(block);
     const minutes = minutesElapsed(block, now);
-    return minutes >= policy[cls].timeoutMinutes;
+    return minutes >= timeoutMinutesForBlock(block, policy);
 }
 /**
  * Apply policy to a single open block. Returns the action taken (none/defaulted/parked).
  * Caller is responsible for persistence/logging side effects not owned by feed.ts.
  */
-export function applyPolicyToBlock(block, policy, now, root) {
+export function applyPolicyToBlock(block, policy, now, root, mailboxRoot) {
     if (block.answer || block.parkedAt || block.defaultedAt) {
         return { blockId: block.blockId, action: 'none' };
     }
@@ -97,7 +102,7 @@ export function applyPolicyToBlock(block, policy, now, root) {
         if (!claim.ok) {
             return { blockId: block.blockId, action: 'none' };
         }
-        const msgId = enqueue(mailboxDir(block.mailboxId, root ?? undefined), {
+        const msgId = enqueue(mailboxDir(block.mailboxId, mailboxRoot), {
             to: block.mailboxId,
             text: safeDefault,
             from: 'policy',

package/dist/lib/feed-ranking.d.ts

@@ -0,0 +1,32 @@
+import type { OpenBlock, FeedAskStats } from './feed.js';
+import type { Classification } from './ask-classifier.js';
+import type { ActiveSession } from './session/active.js';
+import type { SessionMeta } from './session/types.js';
+export interface FeedSessionSignal {
+    sessionId?: string;
+    mailboxId?: string;
+    kind?: string;
+    host?: string;
+    context?: ActiveSession['context'];
+    runtime?: string;
+    pid?: number;
+    cwd?: string;
+    startedAtMs?: number;
+    status?: ActiveSession['status'];
+    tokPerSec?: number;
+    costUsd?: number;
+    durationMs?: number;
+    cloudProvider?: string;
+    cloudTaskId?: string;
+}
+export interface RankedFeedBlock extends OpenBlock {
+    delayRank: NonNullable<OpenBlock['delayRank']>;
+}
+export declare function buildSessionSignals(active: ActiveSession[], metas?: SessionMeta[]): FeedSessionSignal[];
+export declare function decisionIrreducibility(c: Classification): number;
+export declare function burnUsdPerHour(signal: FeedSessionSignal | undefined, block: OpenBlock): number;
+export declare function rankFeedBlocks(blocks: OpenBlock[], signals?: FeedSessionSignal[], now?: Date): RankedFeedBlock[];
+export declare function recentAskCount(stats: FeedAskStats, now?: Date): number;
+export declare function needyControlCards(stats: FeedAskStats[], signals?: FeedSessionSignal[], now?: Date, threshold?: number): OpenBlock[];
+export declare function runawayControlCards(signals: FeedSessionSignal[], now?: Date): OpenBlock[];
+export declare function synthesizeControlCards(signals: FeedSessionSignal[], stats: FeedAskStats[], now?: Date): OpenBlock[];