@phnx-labs/agents-cli 1.12.0 → 1.14.2

package/dist/lib/cloud/stream.js

@@ -0,0 +1,194 @@
+/**
+ * Server-Sent Events parser and terminal renderer for cloud task output.
+ *
+ * Used by `agents cloud logs -f` to stream live output from a running task
+ * and by the post-dispatch follow mode to show progress inline.
+ */
+import chalk from 'chalk';
+/**
+ * Translate a (server-emitted SSE event name, raw data string) pair into a
+ * typed CloudEvent. Unknown event names are surfaced as `{ type: 'unknown' }`
+ * rather than dropped — that's the whole point of widening the taxonomy.
+ */
+function decodeSSEFrame(name, data, timestamp) {
+    let parsed = {};
+    try {
+        parsed = data ? JSON.parse(data) : {};
+    }
+    catch {
+        // non-JSON payloads are kept as raw text below
+    }
+    switch (name) {
+        case 'status':
+            return { type: 'status', status: parsed.status ?? 'running', timestamp };
+        case 'text':
+        case 'output':
+        case 'message':
+            return { type: 'text', content: parsed.content ?? data, timestamp };
+        case 'thinking':
+            return { type: 'thinking', content: parsed.content ?? data, timestamp };
+        case 'tool_use':
+            return { type: 'tool_use', tool: parsed.tool ?? '', input: parsed.input, timestamp };
+        case 'tool_result':
+            return { type: 'tool_result', tool: parsed.tool ?? '', output: parsed.output, timestamp };
+        case 'usage':
+            return {
+                type: 'usage',
+                model: parsed.model,
+                inputTokens: parsed.inputTokens,
+                outputTokens: parsed.outputTokens,
+                timestamp,
+            };
+        case 'done':
+            return {
+                type: 'done',
+                status: parsed.status,
+                prUrl: parsed.prUrl,
+                summary: typeof parsed.output === 'string' ? parsed.output.slice(0, 2000) : parsed.summary,
+                timestamp,
+            };
+        case 'error':
+            return { type: 'error', message: parsed.message ?? data, timestamp };
+        default:
+            return { type: 'unknown', name, data, timestamp };
+    }
+}
+/**
+ * Parse a Server-Sent Events stream into CloudEvents.
+ * Handles `event:`, `data:`, keepalive comments, and multi-line data.
+ */
+export async function* parseSSE(response) {
+    if (!response.body)
+        return;
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    let currentEvent = '';
+    let currentData = '';
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            const lines = buffer.split('\n');
+            buffer = lines.pop() ?? '';
+            for (const line of lines) {
+                // Keepalive comment
+                if (line.startsWith(':'))
+                    continue;
+                if (line.startsWith('event: ')) {
+                    currentEvent = line.slice(7).trim();
+                }
+                else if (line.startsWith('data: ')) {
+                    currentData += (currentData ? '\n' : '') + line.slice(6);
+                }
+                else if (line === '') {
+                    // Empty line = end of event
+                    if (currentEvent || currentData) {
+                        yield decodeSSEFrame(currentEvent || 'output', currentData, new Date().toISOString());
+                        currentEvent = '';
+                        currentData = '';
+                    }
+                }
+            }
+        }
+        // Flush remaining
+        if (currentEvent || currentData) {
+            yield decodeSSEFrame(currentEvent || 'output', currentData, new Date().toISOString());
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+/**
+ * Render a stream of CloudEvents to the terminal.
+ * Returns the final status and summary when the stream ends.
+ */
+export async function renderStream(events, options) {
+    let lastStatus = 'running';
+    let summary;
+    let prUrl;
+    for await (const event of events) {
+        if (options?.json) {
+            process.stdout.write(JSON.stringify(event) + '\n');
+            continue;
+        }
+        switch (event.type) {
+            case 'status': {
+                lastStatus = event.status;
+                process.stderr.write(`${statusLabel(lastStatus)}\n`);
+                break;
+            }
+            case 'text': {
+                process.stdout.write(event.content);
+                break;
+            }
+            case 'thinking': {
+                process.stderr.write(chalk.dim(`[thinking] ${event.content}\n`));
+                break;
+            }
+            case 'tool_use': {
+                process.stderr.write(chalk.cyan(`[tool] ${event.tool}\n`));
+                break;
+            }
+            case 'tool_result': {
+                // Tool results are usually verbose; just acknowledge inline.
+                process.stderr.write(chalk.dim(`[tool_result] ${event.tool}\n`));
+                break;
+            }
+            case 'usage': {
+                const parts = [];
+                if (event.model)
+                    parts.push(event.model);
+                if (event.inputTokens != null)
+                    parts.push(`in=${event.inputTokens}`);
+                if (event.outputTokens != null)
+                    parts.push(`out=${event.outputTokens}`);
+                if (parts.length > 0) {
+                    process.stderr.write(chalk.dim(`[usage] ${parts.join(' ')}\n`));
+                }
+                break;
+            }
+            case 'done': {
+                lastStatus = event.status ?? 'completed';
+                summary = event.summary;
+                prUrl = event.prUrl;
+                process.stderr.write(`\n${statusLabel(lastStatus)}\n`);
+                break;
+            }
+            case 'error': {
+                process.stderr.write(chalk.red(`Error: ${event.message}\n`));
+                lastStatus = 'failed';
+                break;
+            }
+            case 'unknown': {
+                process.stderr.write(chalk.dim(`[${event.name}] ${event.data}\n`));
+                break;
+            }
+        }
+    }
+    return { status: lastStatus, summary, prUrl };
+}
+/** Map a task status string to a colored terminal label. */
+function statusLabel(status) {
+    switch (status) {
+        case 'queued':
+        case 'allocating':
+            return chalk.blue(`[${status}]`);
+        case 'running':
+            return chalk.yellow(`[${status}]`);
+        case 'completed':
+            return chalk.green('[completed]');
+        case 'needs_review':
+        case 'input_required':
+            return chalk.magenta('[needs review]');
+        case 'failed':
+            return chalk.red('[failed]');
+        case 'cancelled':
+            return chalk.gray('[cancelled]');
+        default:
+            return chalk.dim(`[${status}]`);
+    }
+}

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

@@ -0,0 +1,205 @@
+/**
+ * Cloud dispatch type definitions.
+ *
+ * Defines the provider-agnostic interface that all cloud backends (Rush, Codex,
+ * Factory) implement, plus the shared task and event types that flow through
+ * the dispatch pipeline.
+ */
+/** Identifier for a supported cloud dispatch backend. */
+export type CloudProviderId = 'rush' | 'codex' | 'factory';
+/**
+ * Lifecycle state of a cloud-dispatched task.
+ *
+ * `idle` represents a long-lived session that has stopped between turns and
+ * can be resumed via `message()`. Distinct from the terminal `completed |
+ * failed | cancelled` states, which cannot transition back to `running`.
+ */
+export type CloudTaskStatus = 'queued' | 'allocating' | 'running' | 'idle' | 'input_required' | 'completed' | 'failed' | 'cancelled';
+/** Snapshot of a dispatched task, stored locally and refreshed from the provider. */
+export interface CloudTask {
+    id: string;
+    provider: CloudProviderId;
+    status: CloudTaskStatus;
+    agent?: string;
+    prompt: string;
+    /**
+     * First (or only) repo the task targets. Kept for back-compat with callers
+     * that treat one task as one repo. For multi-repo dispatches, see `repos`.
+     */
+    repo?: string;
+    /**
+     * All repos the task targets, in dispatch order. Populated for multi-repo
+     * dispatches (Rush Cloud, and any provider that supports it). `repo`
+     * mirrors `repos[0]` when both are set.
+     */
+    repos?: string[];
+    branch?: string;
+    prUrl?: string;
+    createdAt: string;
+    updatedAt: string;
+    summary?: string;
+}
+/**
+ * Single event emitted by a running cloud task.
+ *
+ * Discriminated union mirroring the local `SessionEvent` taxonomy so cloud
+ * streams can be rendered with the same UI primitives as local sessions. The
+ * `unknown` variant catches event names the provider emits that the client
+ * doesn't recognize — surfacing them rather than silently dropping is the
+ * point.
+ */
+export type CloudEvent = {
+    type: 'text';
+    content: string;
+    timestamp?: string;
+} | {
+    type: 'thinking';
+    content: string;
+    timestamp?: string;
+} | {
+    type: 'tool_use';
+    tool: string;
+    input: unknown;
+    timestamp?: string;
+} | {
+    type: 'tool_result';
+    tool: string;
+    output: unknown;
+    timestamp?: string;
+} | {
+    type: 'status';
+    status: CloudTaskStatus;
+    timestamp?: string;
+} | {
+    type: 'usage';
+    model?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    timestamp?: string;
+} | {
+    type: 'done';
+    status?: CloudTaskStatus;
+    prUrl?: string;
+    summary?: string;
+    timestamp?: string;
+} | {
+    type: 'error';
+    message: string;
+    timestamp?: string;
+} | {
+    type: 'unknown';
+    name: string;
+    data: string;
+    timestamp?: string;
+};
+/** Reference to a skill that should ride along with a cloud dispatch. */
+export interface SkillRef {
+    id: string;
+    version?: string;
+}
+/** A vision attachment carried along with a prompt (base64-encoded image bytes). */
+export interface ImageAttachment {
+    data: string;
+    mimeType: 'image/png' | 'image/jpeg' | 'image/webp';
+}
+/** Maximum images allowed per dispatch (matches Cursor Background Agents). */
+export declare const MAX_IMAGES_PER_DISPATCH = 5;
+/** Parameters for dispatching a new cloud task. */
+export interface DispatchOptions {
+    prompt: string;
+    agent?: string;
+    /**
+     * Legacy single-repo target. Still honored: if `repos` is empty, this
+     * becomes the only repo. Providers that support multi-repo treat
+     * `repos = [repo]` and `repo` as equivalent.
+     */
+    repo?: string;
+    /**
+     * One or more repos the dispatch targets. Repeatable on the CLI via
+     * `--repo`. Providers handle multi-repo differently:
+     *   - Rush Cloud clones each into /workspace/<owner>/<name>/
+     *   - Codex Cloud rejects (multi-repo requires an env that bundles them)
+     *   - Factory (local) clones each into the workspace before dispatch
+     */
+    repos?: string[];
+    branch?: string;
+    timeout?: string;
+    model?: string;
+    /**
+     * Skills to ship with the dispatch. Providers that support skills mount
+     * them in the pod's skills directory before the agent runs. Providers
+     * without skill support reject via `capabilities().skills === false`.
+     */
+    skills?: SkillRef[];
+    /**
+     * Image attachments for vision-enabled dispatch (e.g., "fix this UI bug,
+     * here's the screenshot"). Capped at MAX_IMAGES_PER_DISPATCH.
+     */
+    images?: ImageAttachment[];
+    /** Provider-specific options (e.g., codex env ID, factory computer name). */
+    providerOptions?: Record<string, unknown>;
+}
+/**
+ * Collapse `repo` + `repos` into a single deduped list. Exported so callers,
+ * tests, and every provider share the same resolution — one source of truth
+ * for "which repos does this dispatch target?".
+ */
+export declare function resolveDispatchRepos(options: DispatchOptions): string[];
+/**
+ * What a provider can actually do. Replaces the single-bool `supports()` so
+ * callers can ask "does this provider support cancel?" without trying and
+ * catching. The CLI gates feature-specific calls on these flags and surfaces
+ * a typed error instead of letting throws bubble.
+ */
+export interface ProviderCapabilities {
+    /** Configured + reachable (auth present, binary installed, etc.). */
+    available: boolean;
+    dispatch: boolean;
+    status: boolean;
+    list: boolean;
+    stream: boolean;
+    cancel: boolean;
+    message: boolean;
+    multiRepo: boolean;
+    skills: boolean;
+    images: boolean;
+}
+/**
+ * Contract that every cloud backend must implement.
+ *
+ * Each provider translates between the unified dispatch interface and its
+ * backend-specific API (Rush Factory Floor, Codex Cloud CLI, Droid daemon).
+ *
+ * `message()` may transition a task from `idle` back to `running`.
+ */
+export interface CloudProvider {
+    id: CloudProviderId;
+    name: string;
+    /** Static capability map for this provider. Read before calling feature methods. */
+    capabilities(): ProviderCapabilities;
+    dispatch(options: DispatchOptions): Promise<CloudTask>;
+    status(taskId: string): Promise<CloudTask>;
+    list(filter?: {
+        status?: CloudTaskStatus;
+    }): Promise<CloudTask[]>;
+    /** Stream live output. Yields events until task completes or caller breaks. */
+    stream(taskId: string): AsyncIterable<CloudEvent>;
+    cancel(taskId: string): Promise<void>;
+    /** Send a follow-up message to a finished/idle/needs_review task. */
+    message(taskId: string, content: string): Promise<void>;
+}
+/** Per-provider configuration stored in the `cloud.providers` section of agents.yaml. */
+export interface CloudProviderConfig {
+    rush?: Record<string, string>;
+    codex?: {
+        env?: string;
+    };
+    factory?: {
+        computer?: string;
+    };
+}
+/** Top-level `cloud` section of agents.yaml. */
+export interface CloudConfig {
+    default_provider?: CloudProviderId;
+    providers?: CloudProviderConfig;
+}

package/dist/lib/cloud/types.js

@@ -0,0 +1,34 @@
+/**
+ * Cloud dispatch type definitions.
+ *
+ * Defines the provider-agnostic interface that all cloud backends (Rush, Codex,
+ * Factory) implement, plus the shared task and event types that flow through
+ * the dispatch pipeline.
+ */
+/** Maximum images allowed per dispatch (matches Cursor Background Agents). */
+export const MAX_IMAGES_PER_DISPATCH = 5;
+/**
+ * Collapse `repo` + `repos` into a single deduped list. Exported so callers,
+ * tests, and every provider share the same resolution — one source of truth
+ * for "which repos does this dispatch target?".
+ */
+export function resolveDispatchRepos(options) {
+    const out = [];
+    const seen = new Set();
+    const candidates = [];
+    if (options.repos)
+        candidates.push(...options.repos);
+    if (options.repo)
+        candidates.push(options.repo);
+    for (const raw of candidates) {
+        const trimmed = typeof raw === 'string' ? raw.trim() : '';
+        if (!trimmed)
+            continue;
+        const key = trimmed.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(trimmed);
+    }
+    return out;
+}

package/dist/lib/command-skills.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Convert slash-command markdown files into Codex skills for Codex releases
+ * that no longer load the legacy prompts/ directory.
+ */
+import type { AgentId } from './types.js';
+export declare function shouldInstallCommandAsSkill(agent: AgentId, version: string): boolean;
+export declare function commandSkillName(commandName: string): string;
+export declare function buildCommandSkillContent(commandName: string, sourcePath: string): string;
+export declare function skillSourceExists(skillName: string, skillSourceDirs: Array<string | null | undefined>): boolean;
+export declare function installCommandSkillToVersion(agentDir: string, commandName: string, sourcePath: string, skillSourceDirs?: Array<string | null | undefined>): {
+    success: boolean;
+    skipped?: boolean;
+    error?: string;
+};
+export declare function listCommandSkillsInVersion(agentDir: string): string[];
+export declare function commandSkillMatches(agentDir: string, commandName: string, sourcePath: string): boolean;
+export declare function removeCommandSkillFromVersion(agentDir: string, commandName: string): {
+    success: boolean;
+    error?: string;
+};

package/dist/lib/command-skills.js

@@ -0,0 +1,142 @@
+/**
+ * Convert slash-command markdown files into Codex skills for Codex releases
+ * that no longer load the legacy prompts/ directory.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'yaml';
+import { supports } from './capabilities.js';
+import { safeJoin } from './paths.js';
+const COMMAND_SKILL_MARKER = 'agents_command';
+function readCommandMetadata(sourcePath) {
+    const content = fs.readFileSync(sourcePath, 'utf-8');
+    const lines = content.split('\n');
+    if (lines[0] !== '---') {
+        return { description: '', body: content };
+    }
+    const endIndex = lines.slice(1).findIndex((line) => line === '---');
+    if (endIndex < 0) {
+        return { description: '', body: content };
+    }
+    const frontmatterEnd = endIndex + 1;
+    const frontmatter = lines.slice(1, frontmatterEnd).join('\n');
+    const body = lines.slice(frontmatterEnd + 1).join('\n').trimStart();
+    try {
+        const parsed = yaml.parse(frontmatter);
+        const description = typeof parsed?.description === 'string' ? parsed.description.trim() : '';
+        return { description, body };
+    }
+    catch {
+        return { description: '', body };
+    }
+}
+function readSkillCommandMarker(skillMdPath) {
+    if (!fs.existsSync(skillMdPath))
+        return null;
+    const content = fs.readFileSync(skillMdPath, 'utf-8');
+    const lines = content.split('\n');
+    if (lines[0] !== '---')
+        return null;
+    const endIndex = lines.slice(1).findIndex((line) => line === '---');
+    if (endIndex < 0)
+        return null;
+    try {
+        const frontmatter = lines.slice(1, endIndex + 1).join('\n');
+        const parsed = yaml.parse(frontmatter);
+        return typeof parsed?.[COMMAND_SKILL_MARKER] === 'string' ? parsed[COMMAND_SKILL_MARKER] : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function shouldInstallCommandAsSkill(agent, version) {
+    if (agent !== 'codex')
+        return false;
+    return !supports(agent, 'commands', version).ok && supports(agent, 'skills', version).ok;
+}
+export function commandSkillName(commandName) {
+    return commandName;
+}
+export function buildCommandSkillContent(commandName, sourcePath) {
+    const { description, body } = readCommandMetadata(sourcePath);
+    const skillDescription = description || `Slash command converted from /${commandName}`;
+    return [
+        '---',
+        `name: ${JSON.stringify(commandSkillName(commandName))}`,
+        `description: ${JSON.stringify(skillDescription)}`,
+        `${COMMAND_SKILL_MARKER}: ${JSON.stringify(commandName)}`,
+        '---',
+        '',
+        `# /${commandName}`,
+        '',
+        `This skill contains the behavior from the legacy \`/${commandName}\` slash command.`,
+        'When invoked with `$' + commandSkillName(commandName) + '`, treat the text after the skill name as the original command arguments.',
+        '',
+        body.trimEnd(),
+        '',
+    ].join('\n');
+}
+export function skillSourceExists(skillName, skillSourceDirs) {
+    return skillSourceDirs.some((dir) => {
+        if (!dir)
+            return false;
+        const candidate = path.join(dir, skillName);
+        return fs.existsSync(candidate) && fs.lstatSync(candidate).isDirectory();
+    });
+}
+export function installCommandSkillToVersion(agentDir, commandName, sourcePath, skillSourceDirs = []) {
+    const skillName = commandSkillName(commandName);
+    if (skillSourceExists(skillName, skillSourceDirs)) {
+        return { success: false, skipped: true, error: `Skill '${skillName}' already exists` };
+    }
+    const skillsDir = safeJoin(agentDir, 'skills');
+    const skillDir = safeJoin(skillsDir, skillName);
+    try {
+        fs.rmSync(skillDir, { recursive: true, force: true });
+        fs.mkdirSync(skillDir, { recursive: true });
+        fs.writeFileSync(safeJoin(skillDir, 'SKILL.md'), buildCommandSkillContent(commandName, sourcePath), 'utf-8');
+        return { success: true };
+    }
+    catch (err) {
+        return { success: false, error: err.message };
+    }
+}
+export function listCommandSkillsInVersion(agentDir) {
+    const skillsDir = path.join(agentDir, 'skills');
+    if (!fs.existsSync(skillsDir))
+        return [];
+    const names = [];
+    for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+        if (!entry.isDirectory() || entry.name.startsWith('.'))
+            continue;
+        const marker = readSkillCommandMarker(path.join(skillsDir, entry.name, 'SKILL.md'));
+        if (marker)
+            names.push(marker);
+    }
+    return names.sort();
+}
+export function commandSkillMatches(agentDir, commandName, sourcePath) {
+    const skillMdPath = path.join(agentDir, 'skills', commandSkillName(commandName), 'SKILL.md');
+    if (!fs.existsSync(skillMdPath))
+        return false;
+    try {
+        return fs.readFileSync(skillMdPath, 'utf-8') === buildCommandSkillContent(commandName, sourcePath);
+    }
+    catch {
+        return false;
+    }
+}
+export function removeCommandSkillFromVersion(agentDir, commandName) {
+    const skillDir = path.join(agentDir, 'skills', commandSkillName(commandName));
+    const skillMdPath = path.join(skillDir, 'SKILL.md');
+    if (readSkillCommandMarker(skillMdPath) !== commandName) {
+        return { success: true };
+    }
+    try {
+        fs.rmSync(skillDir, { recursive: true, force: true });
+        return { success: true };
+    }
+    catch (err) {
+        return { success: false, error: err.message };
+    }
+}

package/dist/lib/commands.d.ts

@@ -1,14 +1,26 @@
+/**
+ * Slash command management -- discovery, installation, and syncing.
+ *
+ * Commands are markdown files in ~/.agents/commands/ exposed as `/command-name`
+ * shortcuts by agents. This module discovers them, converts between formats
+ * (markdown for Claude/Codex, TOML for Gemini), and installs them into
+ * agent version homes.
+ */
 import type { AgentId, CommandInstallation } from './types.js';
+/** Scope of a command: user-global or project-local. */
 export type CommandScope = 'user' | 'project';
+/** Parsed metadata from a command file's YAML frontmatter. */
 export interface CommandMetadata {
     name: string;
     description: string;
 }
+/** Result of validating command metadata. */
 export interface ValidationResult {
     valid: boolean;
     errors: string[];
     warnings: string[];
 }
+/** A command discovered in a repository's commands/ directory. */
 export interface DiscoveredCommand {
     name: string;
     description: string;
@@ -16,16 +28,22 @@ export interface DiscoveredCommand {
     isShared: boolean;
     validation: ValidationResult;
 }
+/** A command installed in an agent's config directory. */
 export interface InstalledCommand {
     name: string;
     scope: CommandScope;
     path: string;
     description?: string;
 }
+/** Parse command metadata (name, description) from YAML frontmatter or TOML headers. */
 export declare function parseCommandMetadata(filePath: string): CommandMetadata | null;
+/** Validate command metadata, returning errors and warnings. */
 export declare function validateCommandMetadata(metadata: CommandMetadata | null, commandName: string): ValidationResult;
+/** Discover all command markdown files in a repository's commands/ directory. */
 export declare function discoverCommands(repoPath: string): DiscoveredCommand[];
+/** Find the source path for a command in a repository. */
 export declare function resolveCommandSource(repoPath: string, commandName: string): string | null;
+/** Install a command into an agent's config directory, with optional format conversion. */
 export declare function installCommand(sourcePath: string, agentId: AgentId, commandName: string, method?: 'symlink' | 'copy'): CommandInstallation & {
     error?: string;
     warnings?: string[];
@@ -77,7 +95,9 @@ export declare function iterCommandsCapableVersions(filter?: {
     agent: AgentId;
     version: string;
 }>;
+/** Remove a command from an agent's config directory. */
 export declare function uninstallCommand(agentId: AgentId, commandName: string): boolean;
+/** List command names installed for an agent in the active version home. */
 export declare function listInstalledCommands(agentId: AgentId): string[];
 /**
  * Check if a command exists for an agent.
@@ -106,7 +126,8 @@ export declare function installCommandCentrally(sourcePath: string, commandName:
     warnings?: string[];
 };
 /**
- * List commands from central ~/.agents/commands/ directory.
+ * List commands from user (~/.agents/commands/) and system (~/.agents-system/commands/) dirs.
+ * User dir takes priority; deduplication preserves first occurrence.
  */
 export declare function listCentralCommands(): string[];
 /**
@@ -118,4 +139,3 @@ export declare function getCommandInfo(name: string): {
     path: string;
     content: string;
 } | null;
-//# sourceMappingURL=commands.d.ts.map