chatbase 0.0.1 → 0.1.1

package/dist/commands/chat/index.js

@@ -0,0 +1,210 @@
+import { Flags } from '@oclif/core';
+import { AgentCommand } from '../../base/agent-command.js';
+import { readStdinToEnd } from '../../base/body-input.js';
+import { fetchRecentHistory, retryChat, runChatTurn, sendChat } from '../../client/chat-helpers.js';
+import { UsageError } from '../../errors/errors.js';
+import { maybeSpinner } from '../../output/spinner.js';
+import { runChatRepl } from '../../repl/chat-repl.js';
+export default class Chat extends AgentCommand {
+    static description = 'Send a message to an agent and print its response';
+    static examples = [
+        '<%= config.bin %> chat -a agt_123 -m "How do I reset my password?"',
+        'echo "summarize our refund policy" | <%= config.bin %> chat -a agt_123',
+        '<%= config.bin %> chat -a agt_123 -m "and then?" --conversation conv_123',
+        '<%= config.bin %> chat -a agt_123 -m "hi" --no-stream',
+        '<%= config.bin %> chat -a agt_123 -m "hi" --json'
+    ];
+    static flags = {
+        ...AgentCommand.baseFlags,
+        message: Flags.string({
+            char: 'm',
+            description: 'Message to send (else read from piped stdin, else an interactive REPL)'
+        }),
+        conversation: Flags.string({
+            description: 'Continue an existing conversation'
+        }),
+        resume: Flags.boolean({
+            description: 'Replay the last few messages when continuing a conversation',
+            dependsOn: ['conversation']
+        }),
+        'no-stream': Flags.boolean({
+            description: 'Wait for the complete response instead of streaming tokens'
+        })
+    };
+    async resolveMessage(flags) {
+        if (flags.message)
+            return flags.message;
+        // A TTY with no -m is handled by run() before this is ever called
+        // (it goes to the interactive REPL instead), so reaching here with
+        // no message means stdin is a pipe that turned out to be empty.
+        const piped = (await readStdinToEnd()).trim();
+        if (piped)
+            return piped;
+        throw new UsageError('No message received on stdin.');
+    }
+    async run() {
+        const { flags } = await this.parse(Chat);
+        if (!flags.message && process.stdin.isTTY && !flags['no-input']) {
+            await this.runInteractive(flags);
+            return;
+        }
+        if (flags.resume) {
+            this.note(flags, this.palette(flags).yellow('! --resume only replays history in the interactive REPL (a TTY with no -m) — ignored here.'));
+        }
+        // Resolve the message first: it's local (no network), so a failure
+        // here doesn't first need working credentials or an agent lookup
+        // round trip to fail fast.
+        const message = await this.resolveMessage(flags);
+        const client = this.apiClient(flags);
+        const agentId = await this.agentId(flags, client);
+        // --json always forces a non-streaming call so the full envelope is
+        // available to print in one shot; --no-stream does the same for
+        // plain-text output. Otherwise stream tokens as they arrive.
+        const stream = !flags.json && !flags['no-stream'];
+        const result = await runChatTurn({
+            stream,
+            quiet: flags.quiet,
+            json: flags.json,
+            call: (onText) => sendChat({
+                client,
+                agentId,
+                message,
+                conversationId: flags.conversation,
+                stream,
+                onText
+            })
+        });
+        if (!flags.json) {
+            this.printConversationHint(flags, agentId, result.conversationId);
+        }
+    }
+    /**
+     * The interactive REPL path: a TTY with no -m and no piped stdin. Builds
+     * the `send`/`retry` deps runChatRepl needs — each wraps `sendChat` with
+     * streaming to stdout and forwards the per-call `signal` the REPL
+     * creates fresh per turn, so Ctrl-C cancels just that one call instead
+     * of the process-wide interrupt signal (which would also poison every
+     * later request in the session — see client/signals.ts).
+     */
+    async runInteractive(flags) {
+        const client = this.apiClient(flags);
+        const agentId = await this.agentId(flags, client);
+        // --resume replays the tail of the conversation so the user sees
+        // where they left off. Best-effort: a failed history fetch must
+        // not block the chat itself.
+        if (flags.conversation && flags.resume) {
+            try {
+                const history = await fetchRecentHistory({
+                    client,
+                    agentId,
+                    conversationId: flags.conversation
+                });
+                if (history.length > 0) {
+                    const dim = this.palette(flags).dim;
+                    this.note(flags, dim(`— resuming ${flags.conversation} —`));
+                    for (const line of history) {
+                        const who = line.role === 'user' ? 'you' : 'agent';
+                        this.note(flags, dim(`${who}: ${line.text}`));
+                    }
+                    this.note(flags, dim('—'));
+                }
+            }
+            catch (err) {
+                // Still best-effort — the conversation continues either way —
+                // but a bad --conversation id and "no history yet" must not
+                // look identical.
+                const detail = err instanceof Error ? err.message : String(err);
+                this.note(flags, this.palette(flags).yellow(`! Could not load history for ${flags.conversation} (${detail}) — continuing without it.`));
+            }
+        }
+        // Streaming still has time-to-first-token dead air — spin until the
+        // first token arrives, then let the tokens themselves be the feedback.
+        const spinUntilFirstToken = () => {
+            const stop = maybeSpinner(flags.quiet, 'Thinking…', 300);
+            let stopped = false;
+            return () => {
+                if (stopped)
+                    return;
+                stopped = true;
+                stop();
+            };
+        };
+        // The server returns the assistant message id in the stream's finish
+        // metadata — remember it so /retry has a real id to send. The retry
+        // endpoint truncates the conversation at that message and re-sends
+        // the user message before it; there is no "last" sentinel.
+        let lastMessageId;
+        const send = async (message, conversationId, signal) => {
+            const stop = spinUntilFirstToken();
+            try {
+                const { conversationId: nextId, messageId } = await sendChat({
+                    client,
+                    agentId,
+                    message,
+                    conversationId,
+                    stream: true,
+                    signal,
+                    onText: (text) => {
+                        stop();
+                        process.stdout.write(text);
+                    }
+                });
+                lastMessageId = messageId ?? lastMessageId;
+                process.stdout.write('\n');
+                return { conversationId: nextId };
+            }
+            finally {
+                stop();
+            }
+        };
+        const retry = async (conversationId, signal) => {
+            if (!lastMessageId) {
+                // Cold /retry on a --conversation the REPL just resumed:
+                // nothing sent this session yet, so look up the last
+                // assistant message (history returns the recent tail —
+                // enough, since /retry targets the latest response).
+                const history = await fetchRecentHistory({
+                    client,
+                    agentId,
+                    conversationId
+                });
+                const lastAssistant = [...history]
+                    .reverse()
+                    .find((line) => line.role === 'assistant' && line.id);
+                if (!lastAssistant) {
+                    throw new UsageError('Nothing to retry yet in this conversation — send a message first.');
+                }
+                lastMessageId = lastAssistant.id;
+            }
+            const stop = spinUntilFirstToken();
+            try {
+                const { messageId } = await retryChat({
+                    client,
+                    agentId,
+                    conversationId,
+                    messageId: lastMessageId,
+                    stream: true,
+                    signal,
+                    onText: (text) => {
+                        stop();
+                        process.stdout.write(text);
+                    }
+                });
+                lastMessageId = messageId ?? lastMessageId;
+                process.stdout.write('\n');
+            }
+            finally {
+                stop();
+            }
+        };
+        const { conversationId } = await runChatRepl({
+            send,
+            retry,
+            input: process.stdin,
+            output: process.stdout,
+            info: (msg) => this.note(flags, msg),
+            initialConversationId: flags.conversation
+        });
+        this.printConversationHint(flags, agentId, conversationId);
+    }
+}

package/dist/commands/chat/retry.js

@@ -0,0 +1,49 @@
+import { Flags } from '@oclif/core';
+import { AgentCommand } from '../../base/agent-command.js';
+import { retryChat, runChatTurn } from '../../client/chat-helpers.js';
+export default class ChatRetry extends AgentCommand {
+    static description = 'Retry generating an assistant response (discards that message and everything after it in the conversation)';
+    static examples = [
+        '<%= config.bin %> chat retry --conversation c_123 -a agt_123 --message-id msg_456',
+        '<%= config.bin %> chat retry --conversation c_123 -a agt_123 --message-id msg_456 --no-stream'
+    ];
+    static flags = {
+        ...AgentCommand.baseFlags,
+        conversation: Flags.string({
+            description: 'The conversation ID to retry in',
+            required: true
+        }),
+        'message-id': Flags.string({
+            description: 'The message ID to retry from',
+            required: true
+        }),
+        'no-stream': Flags.boolean({
+            description: 'Wait for the complete response instead of streaming tokens'
+        })
+    };
+    async run() {
+        const { flags } = await this.parse(ChatRetry);
+        const client = this.apiClient(flags);
+        const agentId = await this.agentId(flags, client);
+        // --json always forces a non-streaming call so the full envelope is
+        // available to print in one shot; --no-stream does the same for
+        // plain-text output. Otherwise stream tokens as they arrive.
+        const stream = !flags.json && !flags['no-stream'];
+        const result = await runChatTurn({
+            stream,
+            quiet: flags.quiet,
+            json: flags.json,
+            call: (onText) => retryChat({
+                client,
+                agentId,
+                conversationId: flags.conversation,
+                messageId: flags['message-id'],
+                stream,
+                onText
+            })
+        });
+        if (!flags.json) {
+            this.printConversationHint(flags, agentId, result.conversationId);
+        }
+    }
+}

package/dist/commands/config/get.js

@@ -0,0 +1,40 @@
+import { Args } from '@oclif/core';
+import { BaseCommand } from '../../base/base-command.js';
+import { resolveAgent, resolveTimeoutMs, resolveTimeoutSource } from '../../config/resolve.js';
+import { UsageError } from '../../errors/errors.js';
+export default class ConfigGet extends BaseCommand {
+    static description = 'Print a resolved CLI configuration value and where it comes from';
+    static examples = [
+        '<%= config.bin %> config get agent',
+        '<%= config.bin %> config get timeout'
+    ];
+    static args = {
+        key: Args.string({
+            required: true,
+            description: 'agent | timeout'
+        })
+    };
+    static flags = { ...BaseCommand.baseFlags };
+    requireAuth = false;
+    async run() {
+        const { args, flags } = await this.parse(ConfigGet);
+        const key = args.key.toLowerCase();
+        if (key === 'agent') {
+            const resolved = resolveAgent();
+            if (!resolved) {
+                this.note(flags, 'agent is not set.');
+                return;
+            }
+            process.stdout.write(`${resolved.value}\n`);
+            this.note(flags, `(from ${resolved.source})`);
+            return;
+        }
+        if (key === 'timeout') {
+            const value = resolveTimeoutMs();
+            process.stdout.write(`${value}\n`);
+            this.note(flags, `(from ${resolveTimeoutSource()})`);
+            return;
+        }
+        throw new UsageError(`Unknown config key "${args.key}". Valid keys: agent, timeout.`);
+    }
+}

package/dist/commands/config/list.js

@@ -0,0 +1,34 @@
+import { BaseCommand } from '../../base/base-command.js';
+import { resolveAgent, resolveTimeoutMs, resolveTimeoutSource } from '../../config/resolve.js';
+export default class ConfigList extends BaseCommand {
+    static description = 'List every resolved CLI configuration value and its source';
+    static examples = ['<%= config.bin %> config list'];
+    static flags = { ...BaseCommand.baseFlags };
+    requireAuth = false;
+    async run() {
+        const { flags } = await this.parse(ConfigList);
+        const agent = resolveAgent();
+        const timeoutMs = resolveTimeoutMs();
+        const rows = [
+            {
+                key: 'agent',
+                value: agent ? agent.value : '<not set>',
+                source: agent ? agent.source : 'default'
+            },
+            {
+                key: 'timeout',
+                value: `${timeoutMs}ms`,
+                source: resolveTimeoutSource()
+            }
+        ];
+        this.printData(flags, rows, rows.map((r) => ({
+            key: r.key,
+            value: r.value,
+            source: r.source
+        })), [
+            { key: 'key', header: 'KEY' },
+            { key: 'value', header: 'VALUE' },
+            { key: 'source', header: 'SOURCE' }
+        ]);
+    }
+}

package/dist/commands/config/set.js

@@ -0,0 +1,106 @@
+import { Args } from '@oclif/core';
+import { BaseCommand } from '../../base/base-command.js';
+import { createApiClient } from '../../client/client.js';
+import { fetchPages } from '../../client/paginate.js';
+import { resolveApiKey } from '../../config/resolve.js';
+import { readUserConfig, writeUserConfig } from '../../config/store.js';
+import { UsageError } from '../../errors/errors.js';
+/** Property names people reach for when about to store a credential —
+ * config set never accepts these, no matter the casing. */
+const SECRET_KEYS = new Set(['apikey', 'api_key']);
+export default class ConfigSet extends BaseCommand {
+    static description = 'Set a CLI configuration value';
+    static examples = [
+        '<%= config.bin %> config set agent agt_123',
+        '<%= config.bin %> config set agent',
+        '<%= config.bin %> config set timeout 60000'
+    ];
+    static args = {
+        key: Args.string({
+            required: true,
+            description: 'agent | timeout'
+        }),
+        value: Args.string({
+            required: false,
+            description: 'New value (omit for agent to pick interactively)'
+        })
+    };
+    static flags = { ...BaseCommand.baseFlags };
+    requireAuth = false;
+    async run() {
+        const { args, flags } = await this.parse(ConfigSet);
+        const key = args.key.toLowerCase();
+        if (SECRET_KEYS.has(key)) {
+            throw new UsageError('Credentials are never stored via `config set` — run `chatbase auth login` instead.');
+        }
+        if (key === 'agent') {
+            if (args.value === '') {
+                // Empty value clears — remove the key entirely instead of
+                // storing "" and printing the awkward "set to " message.
+                const { agent: _cleared, ...rest } = readUserConfig();
+                writeUserConfig(rest);
+                this.success(flags, 'agent cleared');
+                return;
+            }
+            const agentId = args.value ?? (await this.pickAgent(flags));
+            writeUserConfig({ ...readUserConfig(), agent: agentId });
+            process.stdout.write(`${agentId}\n`);
+            this.success(flags, `agent set to ${agentId}`);
+            this.warnIfShadowed(flags);
+            return;
+        }
+        if (key === 'timeout') {
+            if (!args.value) {
+                throw new UsageError('Usage: chatbase config set timeout <milliseconds>');
+            }
+            const timeoutMs = Number(args.value);
+            if (!/^\d+$/.test(args.value) || timeoutMs < 1) {
+                throw new UsageError('timeout must be a positive integer number of milliseconds (>= 1).');
+            }
+            writeUserConfig({
+                ...readUserConfig(),
+                timeoutMs
+            });
+            process.stdout.write(`${args.value}\n`);
+            this.success(flags, `timeout set to ${args.value}ms`);
+            return;
+        }
+        throw new UsageError(`Unknown config key "${args.key}". Valid keys: agent, timeout.`);
+    }
+    warnIfShadowed(flags) {
+        const yellow = this.palette(flags).yellow;
+        const env = process.env.CHATBASE_AGENT_ID;
+        if (env && env.length > 0) {
+            this.note(flags, yellow(`! CHATBASE_AGENT_ID=${env} is set and takes precedence — unset it for this value to apply.`));
+        }
+    }
+    /** No value given for `config set agent`: prompt with a picker over
+     * GET /agents, but only when there's a TTY to prompt on. */
+    async pickAgent(flags) {
+        if (!process.stdin.isTTY || flags['no-input']) {
+            throw new UsageError('config set agent requires a value in scripts and CI. Usage: chatbase config set agent <agentId>');
+        }
+        const resolved = resolveApiKey();
+        if (!resolved) {
+            throw new UsageError('Not authenticated. Run `chatbase auth login`, or set CHATBASE_API_KEY.');
+        }
+        // Paginate through every page (fetchPages, same helper
+        // resolveAgentRef in agent-ref.ts uses) so the picker offers every
+        // agent in the workspace, not just whatever fits on the first page.
+        const client = createApiClient({ apiKey: resolved.value });
+        const { items: agents } = await fetchPages((query) => client.GET('/agents', { params: { query } }), {
+            all: true
+        });
+        if (agents.length === 0) {
+            throw new UsageError('No agents found in this workspace — create one first with `chatbase agents create`.');
+        }
+        const { select } = await import('@inquirer/prompts');
+        return select({
+            message: 'Select an agent:',
+            choices: agents.map((a) => ({
+                name: `${a.name ?? a.id} (${a.id})`,
+                value: a.id
+            }))
+        });
+    }
+}

package/dist/commands/conversations/export.js

@@ -0,0 +1,75 @@
+import fs from 'node:fs';
+import { Flags } from '@oclif/core';
+import { AgentCommand } from '../../base/agent-command.js';
+import { fetchPages } from '../../client/paginate.js';
+import { UsageError } from '../../errors/errors.js';
+export default class ConversationsExport extends AgentCommand {
+    static summary = 'Export conversations from every source, with full message history';
+    static description = 'Export conversations with full message history, newest first.\n\n' +
+        'This is the only endpoint that returns conversations from every ' +
+        'source — the chat bubble and external integrations (Slack, WhatsApp, ' +
+        'Instagram, Messenger, and the like) as well as API-created ones. ' +
+        'Prefer it over `conversations list` whenever you need real traffic ' +
+        'rather than just programmatically created conversations. Each item ' +
+        'embeds its own `messages` array, so no follow-up `conversations get` ' +
+        'or `messages list` call is needed (and neither works for ' +
+        'bubble/integration conversations).';
+    static examples = [
+        '<%= config.bin %> conversations export -a agt_123',
+        '<%= config.bin %> conversations export -a agt_123 --all -o export.json'
+    ];
+    // Export is a data-export command, not a display one: it always emits
+    // the raw API JSON, in both pretty and --json mode (--plain/--json are
+    // inherited but no-ops here — kept only so `-h` documents them like
+    // every other command).
+    static flags = {
+        ...AgentCommand.baseFlags,
+        cursor: Flags.string({
+            description: 'Opaque cursor from a previous response'
+        }),
+        // The API caps this endpoint at 20 per page — not the 100 that
+        // ListCommand's shared --limit allows — which is why export declares
+        // its own flag instead of inheriting that base.
+        limit: Flags.integer({
+            description: 'Items per page (1-20, default 20)',
+            min: 1,
+            max: 20
+        }),
+        all: Flags.boolean({ description: 'Fetch every page' }),
+        output: Flags.string({
+            char: 'o',
+            description: 'Write export JSON to a file instead of stdout'
+        })
+    };
+    async run() {
+        const { flags } = await this.parse(ConversationsExport);
+        const client = this.apiClient(flags);
+        const agentId = await this.agentId(flags, client);
+        const { pages, items } = await fetchPages((query) => client.GET('/agents/{agentId}/conversations/export', {
+            params: { path: { agentId }, query }
+        }), { limit: flags.limit, cursor: flags.cursor, all: flags.all });
+        const last = pages.at(-1);
+        // Single page stays byte-for-byte the API's envelope; --all merges
+        // `data` across pages but keeps that same shape so downstream
+        // consumers parse one thing either way.
+        const raw = pages.length === 1
+            ? pages[0]
+            : { data: items, pagination: last?.pagination };
+        const json = `${JSON.stringify(raw, null, 2)}\n`;
+        if (flags.output) {
+            try {
+                fs.writeFileSync(flags.output, json);
+            }
+            catch (e) {
+                throw new UsageError(`Cannot write to ${flags.output}: ${e.code ?? e.message}`);
+            }
+            this.success(flags, `Exported conversations to ${flags.output}`);
+        }
+        else {
+            process.stdout.write(json);
+        }
+        if (!flags.all && last?.pagination.hasMore && last.pagination.cursor) {
+            this.note(flags, `More results: rerun with --cursor ${last.pagination.cursor} (or use --all)`);
+        }
+    }
+}

package/dist/commands/conversations/get.js

@@ -0,0 +1,69 @@
+import { Args, Flags } from '@oclif/core';
+import { AgentCommand } from '../../base/agent-command.js';
+import { throwIfError } from '../../client/client.js';
+import { UsageError } from '../../errors/errors.js';
+import { formatEpochSeconds } from '../../output/render.js';
+const COLUMNS = [
+    { key: 'id', header: 'ID' },
+    { key: 'title', header: 'TITLE' },
+    { key: 'status', header: 'STATUS' },
+    { key: 'createdAt', header: 'CREATED' },
+    { key: 'updatedAt', header: 'UPDATED' }
+];
+export default class ConversationsGet extends AgentCommand {
+    static description = 'Show one conversation';
+    static examples = [
+        '<%= config.bin %> conversations get conv_123 -a agt_123',
+        '<%= config.bin %> conversations get --conversation conv_123 -a agt_123'
+    ];
+    static args = {
+        conversationId: Args.string({
+            required: false,
+            description: 'Conversation ID (alternative to --conversation)'
+        })
+    };
+    static flags = {
+        ...AgentCommand.baseFlags,
+        conversation: Flags.string({
+            description: 'Conversation ID'
+        })
+    };
+    async run() {
+        const { args, flags } = await this.parse(ConversationsGet);
+        // Positional and flag are alternatives — `agents get <id>` set the
+        // positional convention, the flag predates it and stays supported.
+        const conversationId = args.conversationId ?? flags.conversation;
+        if (!conversationId) {
+            throw new UsageError('Missing conversation ID. Pass it positionally (`conversations get <id>`) or via --conversation.');
+        }
+        if (args.conversationId && flags.conversation) {
+            throw new UsageError('Pass the conversation ID either positionally or via --conversation, not both.');
+        }
+        const client = this.apiClient(flags);
+        const agentId = await this.agentId(flags, client);
+        const { data, error, response } = await client.GET('/agents/{agentId}/conversations/{conversationId}', {
+            params: {
+                path: { agentId, conversationId }
+            }
+        });
+        throwIfError(response, error);
+        // GetConversationResponse wraps the conversation (with nested
+        // messages) in { data, pagination }; --json prints that whole
+        // envelope as-is, but the display row only needs the metadata
+        // fields shared with `conversations list`.
+        const conversation = data.data;
+        // Humans read ISO dates; --plain keeps the raw epoch for scripts.
+        const formatTimestamp = this.mode(flags) === 'pretty'
+            ? formatEpochSeconds
+            : (v) => String(v ?? '');
+        this.printData(flags, data, [
+            {
+                id: String(conversation.id ?? ''),
+                title: String(conversation.title ?? ''),
+                status: String(conversation.status ?? ''),
+                createdAt: formatTimestamp(conversation.createdAt),
+                updatedAt: formatTimestamp(conversation.updatedAt)
+            }
+        ], COLUMNS);
+    }
+}

package/dist/commands/conversations/list.js

@@ -0,0 +1,75 @@
+import { Flags } from '@oclif/core';
+import { ListCommand } from '../../base/list-command.js';
+import { fetchPages } from '../../client/paginate.js';
+import { formatEpochSeconds } from '../../output/render.js';
+const COLUMNS = [
+    { key: 'id', header: 'ID' },
+    { key: 'title', header: 'TITLE' },
+    { key: 'status', header: 'STATUS' },
+    { key: 'createdAt', header: 'CREATED' },
+    { key: 'updatedAt', header: 'UPDATED' }
+];
+/** Printed after every result: the endpoint's scope is the single most
+ * common source of "the CLI is broken" reports, because an agent whose
+ * traffic is all widget/Slack legitimately lists zero rows here. */
+const SCOPE_NOTE = 'Note: API-created conversations only — use `chatbase conversations export` for widget and integration conversations.';
+export default class ConversationsList extends ListCommand {
+    static summary = 'List an agent’s API-created conversations';
+    static description = 'List conversations for an agent, newest first.\n\n' +
+        'Scope: the API v2 list endpoint returns only conversations created ' +
+        'programmatically through the API. Conversations from the chat bubble ' +
+        'and external integrations (Slack, WhatsApp, Instagram, Messenger, and ' +
+        'the like) are not accessible here and are not counted in `total`. ' +
+        'Use `chatbase conversations export` to read conversations from every ' +
+        'source — it also embeds full message history, which `conversations ' +
+        'get` and `messages list` cannot retrieve for those conversations.';
+    static examples = [
+        '<%= config.bin %> conversations list -a agt_123',
+        '<%= config.bin %> conversations list -a agt_123 --user usr_456',
+        '<%= config.bin %> conversations list -a agt_123 --all --json'
+    ];
+    static flags = {
+        ...ListCommand.baseFlags,
+        user: Flags.string({
+            description: 'List conversations for a specific user (uses GET /users/{userId}/conversations)'
+        })
+    };
+    async run() {
+        const { flags } = await this.parse(ConversationsList);
+        const client = this.apiClient(flags);
+        const agentId = await this.agentId(flags, client);
+        const fetcherPath = flags.user
+            ? '/agents/{agentId}/users/{userId}/conversations'
+            : '/agents/{agentId}/conversations';
+        const { pages, items } = await fetchPages((query) => client.GET(fetcherPath, {
+            params: {
+                path: {
+                    agentId,
+                    ...(flags.user ? { userId: flags.user } : {})
+                },
+                query
+            }
+        }), { limit: flags.limit, cursor: flags.cursor, all: flags.all });
+        // Humans read ISO dates; --plain keeps the raw epoch for scripts.
+        const formatTimestamp = this.mode(flags) === 'pretty'
+            ? formatEpochSeconds
+            : (v) => String(v ?? '');
+        const rows = items.map((c) => ({
+            id: String(c.id ?? ''),
+            title: String(c.title ?? ''),
+            status: String(c.status ?? ''),
+            createdAt: formatTimestamp(c.createdAt),
+            updatedAt: formatTimestamp(c.updatedAt)
+        }));
+        const last = pages.at(-1);
+        // --json must stay the raw API shape even when --all merges pages
+        const raw = pages.length === 1
+            ? pages[0]
+            : { data: items, pagination: last?.pagination };
+        this.printData(flags, raw, rows, COLUMNS);
+        if (!flags.all && last?.pagination.hasMore && last.pagination.cursor) {
+            this.note(flags, `More results: rerun with --cursor ${last.pagination.cursor} (or use --all)`);
+        }
+        this.note(flags, SCOPE_NOTE);
+    }
+}