@phnx-labs/agents-cli 0.1.0

package/dist/commands/profiles.js

@@ -0,0 +1,242 @@
+import chalk from 'chalk';
+import * as fs from 'fs';
+import { listProfiles, readProfile, writeProfile, deleteProfile, profileExists, profileFromPreset, getPresetForProfile, } from '../lib/profiles.js';
+import { getPreset, listPresets } from '../lib/profiles-presets.js';
+import { hasKeychainToken, keychainItemName, setKeychainToken, deleteKeychainToken, } from '../lib/profiles-keychain.js';
+import { isInteractiveTerminal } from './utils.js';
+async function promptForSecret(message) {
+    if (!isInteractiveTerminal()) {
+        throw new Error('A secret is required but the shell is not interactive. Pipe the key via stdin (--key-stdin).');
+    }
+    const { password } = await import('@inquirer/prompts');
+    return await password({ message, mask: true });
+}
+function readStdinSync() {
+    const chunks = [];
+    const buf = Buffer.alloc(65536);
+    while (true) {
+        let bytesRead;
+        try {
+            bytesRead = fs.readSync(0, buf, 0, buf.length, null);
+        }
+        catch {
+            break;
+        }
+        if (bytesRead === 0)
+            break;
+        chunks.push(Buffer.from(buf.subarray(0, bytesRead)));
+    }
+    return Buffer.concat(chunks).toString('utf-8').trim();
+}
+async function ensureProviderToken(provider, signupUrl, fromStdin) {
+    const item = keychainItemName(provider);
+    if (hasKeychainToken(item)) {
+        return;
+    }
+    let token;
+    if (fromStdin) {
+        token = readStdinSync();
+        if (!token) {
+            throw new Error('No key received on stdin.');
+        }
+    }
+    else {
+        const hint = signupUrl ? ` (get one at ${signupUrl})` : '';
+        token = await promptForSecret(`Enter API key for ${provider}${hint}`);
+    }
+    setKeychainToken(item, token);
+    console.log(chalk.green(`Stored in keychain: ${item}`));
+}
+function renderProfileRow(p) {
+    const host = p.host.version ? `${p.host.agent}@${p.host.version}` : p.host.agent;
+    const model = p.env.ANTHROPIC_MODEL || p.env.OPENAI_MODEL || p.env.GEMINI_MODEL || '-';
+    const provider = p.provider || (p.auth?.keychainItem?.split('.')[1]) || '-';
+    return `${chalk.cyan(p.name.padEnd(16))} ${host.padEnd(14)} ${provider.padEnd(12)} ${chalk.gray(model)}`;
+}
+export function registerProfilesCommands(program) {
+    const cmd = program
+        .command('profiles')
+        .description('Named bundles of (host CLI, endpoint, model, auth) — run Kimi/DeepSeek/Qwen/etc through Claude Code without a proxy.')
+        .addHelpText('after', `
+A profile pins a host CLI (claude, codex, gemini, ...) to a non-default endpoint
+and model, with a keychain-backed API key. Running 'agents run <profile>' spawns
+the host CLI with the right env vars — no plaintext tokens, no local proxy.
+
+Built-in presets (via OpenRouter, one shared key):
+  kimi       Kimi K2.5           (top HumanEval, reasoning — interactive only)
+  kimi-chat  Kimi K2 0905        (non-reasoning, print-safe)
+  minimax    MiniMax M2.5        (top SWE-bench, reasoning)
+  glm        GLM 5               (top Chatbot Arena among open-weight, reasoning)
+  qwen       Qwen3 Coder Next    (latest coding Qwen, print-safe)
+  deepseek   DeepSeek Chat V3    (latest non-reasoning chat, print-safe)
+
+Run 'agents profiles presets' for the full list with pricing and context sizes.
+
+Typical flow:
+  agents profiles add kimi             # prompts for OpenRouter key, stored in Keychain
+  agents run kimi "refactor this"      # Claude Code UI, Kimi model responses
+  agents profiles add deepseek         # reuses OpenRouter key, no re-prompt
+
+Managing keys:
+  agents profiles login openrouter     # rotate the key (shared across openrouter profiles)
+  agents profiles logout openrouter    # remove from Keychain
+
+Custom endpoints — drop a YAML file at ~/.agents/profiles/<name>.yml:
+  name: local-llama
+  host: { agent: claude }
+  env:
+    ANTHROPIC_BASE_URL: http://localhost:11434
+    ANTHROPIC_MODEL: llama-3.3-70b
+  auth:
+    envVar: ANTHROPIC_AUTH_TOKEN
+    keychainItem: agents-cli.ollama.token
+
+Profiles store no secrets — safe to 'agents push' to a shared repo.
+`);
+    cmd
+        .command('list')
+        .alias('ls')
+        .description('List configured profiles')
+        .action(() => {
+        const profiles = listProfiles();
+        if (profiles.length === 0) {
+            console.log(chalk.gray('No profiles configured.'));
+            console.log(chalk.gray('Try: agents profiles add kimi'));
+            console.log(chalk.gray('     agents profiles presets'));
+            return;
+        }
+        console.log(chalk.bold(`${'NAME'.padEnd(16)} ${'HOST'.padEnd(14)} ${'PROVIDER'.padEnd(12)} MODEL`));
+        for (const p of profiles) {
+            console.log(renderProfileRow(p));
+        }
+    });
+    cmd
+        .command('presets')
+        .description('List built-in presets (OpenRouter + direct providers)')
+        .action(() => {
+        const presets = listPresets();
+        console.log(chalk.bold(`${'NAME'.padEnd(14)} ${'PROVIDER'.padEnd(12)} DESCRIPTION`));
+        for (const p of presets) {
+            console.log(`${chalk.cyan(p.name.padEnd(14))} ${p.provider.padEnd(12)} ${chalk.gray(p.description)}`);
+        }
+    });
+    cmd
+        .command('view <name>')
+        .alias('show')
+        .description('Show a profile (env, host, auth source, preset link)')
+        .action((name) => {
+        try {
+            const p = readProfile(name);
+            console.log(chalk.bold(p.name));
+            if (p.description)
+                console.log(chalk.gray(p.description));
+            console.log();
+            console.log(chalk.bold('Host:'), p.host.agent + (p.host.version ? `@${p.host.version}` : ''));
+            if (p.provider)
+                console.log(chalk.bold('Provider:'), p.provider);
+            if (p.preset)
+                console.log(chalk.bold('Preset:'), p.preset);
+            console.log();
+            console.log(chalk.bold('Env:'));
+            for (const [k, v] of Object.entries(p.env)) {
+                console.log(`  ${k}=${v}`);
+            }
+            if (p.auth) {
+                console.log();
+                console.log(chalk.bold('Auth:'));
+                const tokenStatus = hasKeychainToken(p.auth.keychainItem) ? chalk.green('stored') : chalk.red('missing');
+                console.log(`  ${p.auth.envVar} <- keychain:${p.auth.keychainItem} (${tokenStatus})`);
+            }
+            const preset = getPresetForProfile(p);
+            if (preset?.signupUrl) {
+                console.log();
+                console.log(chalk.gray(`Sign up: ${preset.signupUrl}`));
+            }
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    cmd
+        .command('add <name>')
+        .description('Add a profile. If <name> matches a built-in preset, the preset is applied. Prompts for API key (once per provider).')
+        .option('--preset <preset>', 'Use a named preset (defaults to <name> if a preset by that name exists)')
+        .option('--version <version>', 'Pin the host CLI version (e.g., 2.1.113)')
+        .option('--key-stdin', 'Read API key from stdin instead of prompting (for scripts/CI)')
+        .option('--force', 'Overwrite an existing profile with the same name')
+        .action(async (name, opts) => {
+        try {
+            if (profileExists(name) && !opts.force) {
+                console.error(chalk.red(`Profile '${name}' already exists. Use --force to overwrite.`));
+                process.exit(1);
+            }
+            const presetName = opts.preset || name;
+            const preset = getPreset(presetName);
+            if (!preset) {
+                console.error(chalk.red(`No preset '${presetName}'.`));
+                console.error(chalk.gray('Available presets: ' + listPresets().map((p) => p.name).join(', ')));
+                console.error(chalk.gray('Or pass --preset <name> to pick explicitly.'));
+                process.exit(1);
+            }
+            await ensureProviderToken(preset.provider, preset.signupUrl, opts.keyStdin);
+            const profile = profileFromPreset(name, preset, opts.version);
+            writeProfile(profile);
+            console.log(chalk.green(`Profile '${name}' added.`));
+            console.log(chalk.gray(`Try: agents run ${name} "hello"`));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    cmd
+        .command('remove <name>')
+        .alias('rm')
+        .description('Delete a profile (keychain token is kept — use `profiles logout <provider>` to remove)')
+        .action((name) => {
+        const existed = deleteProfile(name);
+        if (!existed) {
+            console.error(chalk.red(`Profile '${name}' not found.`));
+            process.exit(1);
+        }
+        console.log(chalk.green(`Profile '${name}' removed.`));
+    });
+    cmd
+        .command('login <provider>')
+        .description('Store or rotate the API key for a provider (e.g., openrouter). Shared across profiles using that provider.')
+        .option('--key-stdin', 'Read API key from stdin')
+        .action(async (provider, opts) => {
+        try {
+            const item = keychainItemName(provider);
+            let token;
+            if (opts.keyStdin) {
+                token = readStdinSync();
+                if (!token)
+                    throw new Error('No key received on stdin.');
+            }
+            else {
+                token = await promptForSecret(`Enter API key for ${provider}`);
+            }
+            setKeychainToken(item, token);
+            console.log(chalk.green(`Stored in keychain: ${item}`));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    cmd
+        .command('logout <provider>')
+        .description('Remove a stored provider key from keychain')
+        .action((provider) => {
+        const item = keychainItemName(provider);
+        const existed = deleteKeychainToken(item);
+        if (!existed) {
+            console.error(chalk.yellow(`No keychain item '${item}' to remove.`));
+            process.exit(1);
+        }
+        console.log(chalk.green(`Removed keychain item: ${item}`));
+    });
+}
+//# sourceMappingURL=profiles.js.map

package/dist/commands/profiles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profiles.js","sourceRoot":"","sources":["../../src/commands/profiles.ts"],"names":[],"mappings":"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"}

package/dist/commands/pty.d.ts

@@ -0,0 +1,20 @@
+/**
+ * PTY Commands
+ *
+ * CLI commands for managing interactive PTY sessions.
+ * Auto-starts the sidecar server on first use.
+ *
+ * Usage:
+ *   agents pty start [--rows 24 --cols 120 --shell zsh --cwd /path]
+ *   agents pty exec  <id> <command>
+ *   agents pty read  <id> [--ms 200]
+ *   agents pty write <id> <input>
+ *   agents pty screen <id>
+ *   agents pty signal <id> [INT|TERM|KILL]
+ *   agents pty list
+ *   agents pty stop  <id>
+ *   agents pty server [start|stop|status]
+ */
+import type { Command } from 'commander';
+export declare function registerPtyCommands(program: Command): void;
+//# sourceMappingURL=pty.d.ts.map

package/dist/commands/pty.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pty.d.ts","sourceRoot":"","sources":["../../src/commands/pty.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAMzC,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAuX1D"}

package/dist/commands/pty.js

@@ -0,0 +1,389 @@
+/**
+ * PTY Commands
+ *
+ * CLI commands for managing interactive PTY sessions.
+ * Auto-starts the sidecar server on first use.
+ *
+ * Usage:
+ *   agents pty start [--rows 24 --cols 120 --shell zsh --cwd /path]
+ *   agents pty exec  <id> <command>
+ *   agents pty read  <id> [--ms 200]
+ *   agents pty write <id> <input>
+ *   agents pty screen <id>
+ *   agents pty signal <id> [INT|TERM|KILL]
+ *   agents pty list
+ *   agents pty stop  <id>
+ *   agents pty server [start|stop|status]
+ */
+import chalk from 'chalk';
+import { ptyRequest, unescapeInput } from '../lib/pty-client.js';
+import { isPtyServerRunning, runPtyServer, getPtyPidPath, getPtyLogPath } from '../lib/pty-server.js';
+import * as fs from 'fs';
+export function registerPtyCommands(program) {
+    const pty = program
+        .command('pty')
+        .description('Drive interactive terminal programs from AI agents. Use this for REPLs, TUIs, or anything needing a real terminal.')
+        .addHelpText('after', `
+Typical session workflow:
+  # Start a new terminal session (returns a session ID)
+  SID=$(agents pty start)
+
+  # Run a command (non-blocking, returns immediately)
+  agents pty exec $SID "python3"
+
+  # Wait a moment, then see what's on screen (clean text, no ANSI)
+  sleep 1 && agents pty screen $SID
+
+  # Send input (supports escape sequences: \\n \\t \\e \\xHH)
+  agents pty write $SID "print('hello')\\n"
+
+  # Read the output again
+  agents pty screen $SID
+
+  # Clean up when done
+  agents pty stop $SID
+
+Use cases:
+  - Drive REPLs (python, node, irb) from agent code
+  - Automate TUI programs (npm init, interactive wizards)
+  - Test CLI tools that require a real PTY
+  - Run the 'agents' CLI itself from another agent
+
+The PTY server auto-starts on first use and runs in the background.
+Use 'agents pty server status' to check health.
+`);
+    // --- Session lifecycle ---
+    pty
+        .command('start')
+        .description('Start a new PTY session and return its ID. The session persists until you stop it.')
+        .option('-r, --rows <n>', 'Terminal height in rows', '24')
+        .option('-c, --cols <n>', 'Terminal width in columns', '120')
+        .option('-s, --shell <shell>', 'Shell to launch (defaults to $SHELL, e.g., zsh, bash)')
+        .option('-d, --cwd <dir>', 'Working directory for the shell')
+        .option('--json', 'Output full session metadata as JSON')
+        .addHelpText('after', `
+Examples:
+  # Start a session and capture its ID
+  SID=$(agents pty start)
+
+  # Start a Python REPL in a specific directory
+  agents pty start --shell python3 --cwd /tmp
+
+  # Start a wider terminal for TUI programs
+  agents pty start --cols 160 --rows 40
+`)
+        .action(async (opts) => {
+        const params = {
+            rows: parseInt(opts.rows, 10),
+            cols: parseInt(opts.cols, 10),
+        };
+        if (opts.shell)
+            params.shell = opts.shell;
+        if (opts.cwd)
+            params.cwd = opts.cwd;
+        const res = await ptyRequest('start', undefined, params);
+        if (!res.ok) {
+            console.error(chalk.red(res.error));
+            process.exit(1);
+        }
+        if (opts.json) {
+            console.log(JSON.stringify(res));
+        }
+        else {
+            console.log(res.id);
+        }
+    });
+    pty
+        .command('exec <id> <command>')
+        .description('Send a command to a PTY session. Returns immediately (non-blocking). Use screen or read to see output.')
+        .option('--wait <ms>', 'Wait this many milliseconds then return the screen (convenience for quick commands)', '0')
+        .option('--json', 'Output as JSON')
+        .addHelpText('after', `
+Examples:
+  # Run a command and return immediately
+  agents pty exec $SID "ls -la"
+
+  # Run a command and wait 500ms to see output
+  agents pty exec $SID "git status" --wait 500
+
+  # Start a long-running process (returns right away)
+  agents pty exec $SID "npm run dev"
+`)
+        .action(async (id, command, opts) => {
+        const res = await ptyRequest('exec', id, { command });
+        if (!res.ok) {
+            console.error(chalk.red(res.error));
+            process.exit(1);
+        }
+        const waitMs = parseInt(opts.wait, 10);
+        if (waitMs > 0) {
+            // Wait then return screen
+            await new Promise(r => setTimeout(r, waitMs));
+            const screen = await ptyRequest('screen', id);
+            if (opts.json) {
+                console.log(JSON.stringify(screen));
+            }
+            else if (screen.ok) {
+                console.log(screen.screen);
+            }
+        }
+        else if (opts.json) {
+            console.log(JSON.stringify(res));
+        }
+    });
+    pty
+        .command('read <id>')
+        .description('Read raw output from the PTY (includes ANSI codes). Use screen for clean text instead.')
+        .option('-m, --ms <ms>', 'Wait up to this many milliseconds for new output (50-5000)', '200')
+        .option('--json', 'Output as JSON')
+        .addHelpText('after', `
+Examples:
+  # Read pending output (wait up to 200ms)
+  agents pty read $SID
+
+  # Read with longer wait for slow commands
+  agents pty read $SID --ms 1000
+`)
+        .action(async (id, opts) => {
+        const ms = parseInt(opts.ms, 10);
+        const res = await ptyRequest('read', id, { ms });
+        if (!res.ok) {
+            console.error(chalk.red(res.error));
+            process.exit(1);
+        }
+        if (opts.json) {
+            console.log(JSON.stringify(res));
+        }
+        else {
+            if (res.output)
+                process.stdout.write(res.output);
+        }
+    });
+    pty
+        .command('write <id> <input>')
+        .description('Send keystrokes to the PTY (like typing into the terminal). Processes escape sequences by default.')
+        .option('--raw', 'Send input literally without processing \\n \\t \\e \\xHH escape codes')
+        .option('--json', 'Output as JSON')
+        .addHelpText('after', `
+Examples:
+  # Send Enter key
+  agents pty write $SID "\\n"
+
+  # Type a command and press Enter
+  agents pty write $SID "ls -la\\n"
+
+  # Send Ctrl-C (interrupt signal)
+  agents pty write $SID "\\x03"
+
+  # Send Escape key
+  agents pty write $SID "\\e"
+
+  # Send literal backslash-n (not newline)
+  agents pty write $SID "\\\\n" --raw
+`)
+        .action(async (id, input, opts) => {
+        const processed = opts.raw ? input : unescapeInput(input);
+        const res = await ptyRequest('write', id, { input: processed });
+        if (!res.ok) {
+            console.error(chalk.red(res.error));
+            process.exit(1);
+        }
+        if (opts.json) {
+            console.log(JSON.stringify(res));
+        }
+    });
+    pty
+        .command('screen <id>')
+        .description('Render the terminal screen as clean text (no ANSI codes). This is what a human sees looking at the terminal.')
+        .option('--json', 'Output as JSON (includes cursor position and dimensions)')
+        .addHelpText('after', `
+Examples:
+  # See what's currently on screen
+  agents pty screen $SID
+
+  # Get screen with cursor position as JSON
+  agents pty screen $SID --json
+
+Use this (not read) when you want clean text for an LLM to parse.
+`)
+        .action(async (id, opts) => {
+        const res = await ptyRequest('screen', id);
+        if (!res.ok) {
+            console.error(chalk.red(res.error));
+            process.exit(1);
+        }
+        if (opts.json) {
+            console.log(JSON.stringify(res));
+        }
+        else {
+            console.log(res.screen);
+        }
+    });
+    pty
+        .command('signal <id> [signal]')
+        .description('Send a POSIX signal to the running process. Defaults to INT (Ctrl-C).')
+        .addHelpText('after', `
+Examples:
+  # Send Ctrl-C (interrupt)
+  agents pty signal $SID INT
+
+  # Terminate gracefully
+  agents pty signal $SID TERM
+
+  # Force kill
+  agents pty signal $SID KILL
+`)
+        .action(async (id, signal) => {
+        const res = await ptyRequest('signal', id, { signal: signal || 'INT' });
+        if (!res.ok) {
+            console.error(chalk.red(res.error));
+            process.exit(1);
+        }
+    });
+    pty
+        .command('resize <id>')
+        .description('Resize a PTY session')
+        .option('-r, --rows <n>', 'Terminal rows')
+        .option('-c, --cols <n>', 'Terminal columns')
+        .action(async (id, opts) => {
+        const params = {};
+        if (opts.rows)
+            params.rows = parseInt(opts.rows, 10);
+        if (opts.cols)
+            params.cols = parseInt(opts.cols, 10);
+        const res = await ptyRequest('resize', id, params);
+        if (!res.ok) {
+            console.error(chalk.red(res.error));
+            process.exit(1);
+        }
+        console.log(`${res.cols}x${res.rows}`);
+    });
+    pty
+        .command('stop <id>')
+        .description('Stop a PTY session and clean up. The session ID becomes invalid.')
+        .addHelpText('after', `
+Example:
+  agents pty stop $SID
+`)
+        .action(async (id) => {
+        const res = await ptyRequest('stop', id);
+        if (!res.ok) {
+            console.error(chalk.red(res.error));
+            process.exit(1);
+        }
+    });
+    // --- Session listing ---
+    pty
+        .command('list')
+        .description('List all active PTY sessions (running or idle).')
+        .option('--json', 'Output as JSON')
+        .addHelpText('after', `
+Example:
+  agents pty list
+`)
+        .action(async (opts) => {
+        const res = await ptyRequest('list');
+        if (!res.ok) {
+            console.error(chalk.red(res.error));
+            process.exit(1);
+        }
+        if (opts.json) {
+            console.log(JSON.stringify(res.sessions));
+            return;
+        }
+        if (res.sessions.length === 0) {
+            console.log(chalk.gray('No active PTY sessions'));
+            return;
+        }
+        for (const s of res.sessions) {
+            const age = formatAge(Date.now() - s.started_at);
+            const status = s.exited
+                ? chalk.red(`exited (${s.exit_code})`)
+                : s.app_active
+                    ? chalk.yellow(`running: ${s.active_command}`)
+                    : chalk.green('idle');
+            console.log(`  ${chalk.bold(s.id)}  pid=${s.pid}  ${s.shell}  ${s.cols}x${s.rows}  ${age}  ${status}`);
+            console.log(`    ${chalk.gray(s.cwd)}`);
+        }
+    });
+    // --- Server management ---
+    const serverCmd = pty
+        .command('server')
+        .description('Manage the PTY sidecar server (auto-starts on first use, usually you do not need this).');
+    serverCmd
+        .command('start')
+        .description('Start the PTY server manually (auto-starts on first pty command anyway).')
+        .action(async () => {
+        if (isPtyServerRunning()) {
+            const pidPath = getPtyPidPath();
+            const pid = fs.existsSync(pidPath) ? fs.readFileSync(pidPath, 'utf-8').trim() : '?';
+            console.log(chalk.yellow(`PTY server already running (PID: ${pid})`));
+            return;
+        }
+        // Use ptyRequest which auto-starts the server
+        const res = await ptyRequest('ping');
+        if (res.ok) {
+            console.log(chalk.green(`PTY server started (PID: ${res.pid})`));
+        }
+        else {
+            console.error(chalk.red('Failed to start PTY server'));
+            process.exit(1);
+        }
+    });
+    serverCmd
+        .command('stop')
+        .description('Stop the PTY server and kill all active sessions.')
+        .action(async () => {
+        if (!isPtyServerRunning()) {
+            console.log(chalk.yellow('PTY server is not running'));
+            return;
+        }
+        const pidPath = getPtyPidPath();
+        try {
+            const pid = parseInt(fs.readFileSync(pidPath, 'utf-8').trim(), 10);
+            process.kill(pid, 'SIGTERM');
+            console.log(chalk.green('PTY server stopped'));
+        }
+        catch {
+            console.error(chalk.red('Failed to stop PTY server'));
+            process.exit(1);
+        }
+    });
+    serverCmd
+        .command('status')
+        .description('Check if the PTY server is running and how many sessions are active.')
+        .action(async () => {
+        const running = isPtyServerRunning();
+        console.log(`  Status: ${running ? chalk.green('running') : chalk.gray('stopped')}`);
+        if (running) {
+            try {
+                const res = await ptyRequest('ping');
+                if (res.ok) {
+                    console.log(`  PID:      ${res.pid}`);
+                    console.log(`  Sessions: ${res.sessions}`);
+                }
+            }
+            catch { }
+        }
+        const logPath = getPtyLogPath();
+        console.log(`  Log:    ${logPath}`);
+    });
+    // Internal: run server in foreground (spawned by auto-start)
+    pty
+        .command('_server', { hidden: true })
+        .description('Run PTY server (internal)')
+        .action(async () => {
+        await runPtyServer();
+    });
+}
+function formatAge(ms) {
+    const secs = Math.floor(ms / 1000);
+    if (secs < 60)
+        return `${secs}s`;
+    const mins = Math.floor(secs / 60);
+    if (mins < 60)
+        return `${mins}m`;
+    const hours = Math.floor(mins / 60);
+    return `${hours}h ${mins % 60}m`;
+}
+//# sourceMappingURL=pty.js.map