@controllerai/cli 0.2.0

package/dist/commands/agent.js

@@ -0,0 +1,813 @@
+import { readFileSync } from 'node:fs';
+import { agentUrl, conversationUrl } from '../appLinks.js';
+import { buildClient } from '../context.js';
+import { CaiError, EXIT, userError } from '../errors.js';
+import { emit, printKeyValues, printTable, truncate, warn } from '../output.js';
+export const resolveConfirmationChoice = (opts) => {
+    if (opts.requireConfirmation === true && opts.confirmation === false) {
+        throw userError('--require-confirmation and --no-confirmation are mutually exclusive.', 'CONFLICTING_INPUT');
+    }
+    if (opts.requireConfirmation === true)
+        return true;
+    if (opts.confirmation === false)
+        return false;
+    return undefined;
+};
+const confirmationReview = (required) => required
+    ? 'approval required before every run'
+    : 'runs without approval — review writes, messages, deletion, and spend before attaching';
+export const directActionToolOp = (input) => ({
+    op: 'add',
+    toolType: 'pipedream',
+    nodeSlug: input.integration,
+    nodeComponentKey: input.action,
+    connectionId: input.connectionId,
+    ...(input.description !== undefined ? { toolDescription: input.description } : {}),
+    // Never omit this field: the product default is no approval while older
+    // backend entry points historically defaulted an omitted value to approval.
+    requiresConfirmation: input.requiresConfirmation,
+});
+const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+const parsePositiveId = (raw, label) => {
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value <= 0) {
+        throw userError(`${label} must be a positive integer.`, 'BAD_ID');
+    }
+    return value;
+};
+export const assertAgentVisibility = (value) => {
+    if (value !== 'private' && value !== 'organization') {
+        throw userError('--value must be private or organization. Public sharing is not supported.', 'BAD_AGENT_VISIBILITY');
+    }
+    return value;
+};
+export const setAgentVisibility = (api, rawAgentId, rawVisibility) => {
+    const agentId = parsePositiveId(rawAgentId, 'agentId');
+    const visibility = assertAgentVisibility(rawVisibility);
+    return api.rest(`/agents/${agentId}/share`, {
+        method: 'PATCH',
+        body: { visibility },
+    });
+};
+export const respondAgentPermission = (api, rawConversationId, requestId, behavior, opts = {}) => {
+    const conversationId = parsePositiveId(rawConversationId, 'conversationId');
+    const normalizedRequestId = requestId.trim();
+    if (!normalizedRequestId) {
+        throw userError('--request must be a non-empty permission request id.', 'BAD_PERMISSION_ID');
+    }
+    const result = behavior === 'allow'
+        ? { behavior: 'allow' }
+        : { behavior: 'deny', message: opts.message?.trim() || 'Denied from the Controller AI CLI.' };
+    return api.rest(`/agent-conversations/${conversationId}/respond-permission`, {
+        method: 'POST',
+        body: {
+            requestId: normalizedRequestId,
+            ...(opts.toolName ? { toolName: opts.toolName } : {}),
+            result,
+        },
+    });
+};
+const instructionText = (opts) => {
+    if (opts.instructions !== undefined && opts.instructionsFile) {
+        throw userError('--instructions and --instructions-file are mutually exclusive.', 'CONFLICTING_INPUT');
+    }
+    if (opts.instructionsFile)
+        return readFileSync(opts.instructionsFile, 'utf8');
+    return opts.instructions;
+};
+const getAgent = (api, id) => api.rest(`/agents/${id}`);
+const updateDraft = async (api, agentId, patch) => {
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        const current = await getAgent(api, agentId);
+        if (!current.updatedAt) {
+            throw userError('Agent response did not include updatedAt; refusing an unsafe draft write.', 'NO_AGENT_HEAD');
+        }
+        try {
+            return await api.rest(`/agents/${agentId}/draft`, {
+                method: 'PATCH',
+                body: { baseUpdatedAt: current.updatedAt, ...patch },
+            });
+        }
+        catch (error) {
+            if (attempt === 0 && error instanceof CaiError && error.exitCode === EXIT.conflict)
+                continue;
+            throw error;
+        }
+    }
+    throw userError('Agent draft update did not complete.', 'AGENT_DRAFT_UPDATE_FAILED');
+};
+const parseSeconds = (raw, label, max = 600) => {
+    const value = Number(raw);
+    if (!Number.isFinite(value) || value <= 0 || value > max) {
+        throw userError(`${label} must be greater than 0 and at most ${max} seconds.`, 'BAD_TIMEOUT');
+    }
+    return value;
+};
+const selectedDraftMode = (opts, defaultDraft) => {
+    if (opts.draft && opts.live) {
+        throw userError('--draft and --live are mutually exclusive.', 'CONFLICTING_AGENT_RAIL');
+    }
+    if (opts.draft)
+        return true;
+    if (opts.live)
+        return false;
+    return defaultDraft;
+};
+const assertConversationRail = (conversation, draft) => {
+    if (conversation.isDraft !== draft) {
+        throw userError(`Conversation ${conversation.id} was created on the ${conversation.isDraft ? 'draft' : 'live'} rail, but the CLI requested ${draft ? 'draft' : 'live'}.`, 'CONVERSATION_RAIL_MISMATCH');
+    }
+};
+const contentText = (content) => typeof content === 'string' ? content : JSON.stringify(content ?? null);
+export const assistantReplyAfter = (history, afterMessageId) => [...(history.messages ?? [])]
+    .reverse()
+    .find(message => message.id > afterMessageId && message.role === 'assistant') ?? null;
+export const completedAgentTurnAfter = (history, afterEventId) => (history.events ?? []).some(event => event.id > afterEventId && event.eventType === 'sdk_message' && event.sdkType === 'result');
+export const pollAgentReply = async (api, conversationId, afterMessageId, afterEventId, timeoutMs, intervalMs = 1_000, wait = sleep) => {
+    const deadline = Date.now() + timeoutMs;
+    let last = null;
+    while (Date.now() < deadline) {
+        last = await api.rest(`/agent-conversations/${conversationId}/history`);
+        if ((last.pendingHitlRequests ?? []).length > 0) {
+            return { kind: 'permission', history: last };
+        }
+        if (['INTERRUPTED', 'CLOSED'].includes(last.conversation?.status ?? '')) {
+            return { kind: 'stopped', history: last };
+        }
+        if (completedAgentTurnAfter(last, afterEventId)) {
+            const reply = assistantReplyAfter(last, afterMessageId);
+            if (reply)
+                return { kind: 'reply', history: last, reply };
+        }
+        await wait(Math.min(intervalMs, Math.max(0, deadline - Date.now())));
+    }
+    return { kind: 'timeout', history: last };
+};
+const requireReply = (result, conversationId) => {
+    if (result.kind === 'reply')
+        return result.reply;
+    if (result.kind === 'permission') {
+        throw userError(`Agent conversation ${conversationId} requested Controller AI permission instead of ` +
+            `completing autonomously. Inspect \`cai agent conversation history ` +
+            `${conversationId} --json\`.`, 'AGENT_PERMISSION_REQUIRED');
+    }
+    if (result.kind === 'stopped') {
+        throw userError(`Agent conversation ${conversationId} stopped with status ${result.history.conversation?.status ?? 'unknown'} before replying.`, 'AGENT_CONVERSATION_STOPPED');
+    }
+    throw userError(`Agent conversation ${conversationId} did not produce an assistant reply before timeout. ` +
+        `Re-read it with \`cai agent conversation history ${conversationId}\`.`, 'AGENT_TEST_TIMEOUT');
+};
+const printConversation = (row, appUrl = null) => {
+    const pairs = [
+        ['conversationId', row.id],
+        ['agentId', row.agentId],
+        ['rail', row.isDraft ? 'draft' : 'live'],
+        ['agent version', row.agentVersionNumber ?? row.agentVersionId ?? '-'],
+        ['status', row.status],
+        ['model', row.model ?? '-'],
+        ['title', row.title ?? '-'],
+    ];
+    if (appUrl)
+        pairs.push(['open in app', appUrl]);
+    printKeyValues(pairs);
+};
+const printHistory = (history) => {
+    if (history.conversation)
+        printConversation(history.conversation);
+    process.stdout.write('\nmessages\n');
+    printTable(['id', 'role', 'content', 'cost', 'created'], (history.messages ?? []).map(message => [
+        message.id,
+        message.role,
+        truncate(contentText(message.content), 100),
+        message.totalCostUsd ?? '-',
+        message.createdAt ?? '-',
+    ]));
+    if ((history.pendingHitlRequests ?? []).length) {
+        process.stdout.write('\npending permissions\n');
+        printTable(['requestId', 'tool'], (history.pendingHitlRequests ?? []).map(request => [
+            request.requestId ?? request.id ?? '-',
+            request.toolName ?? '-',
+        ]));
+        const request = history.pendingHitlRequests?.[0];
+        const requestId = request?.requestId ?? request?.id;
+        if (requestId !== undefined) {
+            const tool = request?.toolName ? ` --tool ${request.toolName}` : '';
+            process.stdout.write(`\nnext: cai agent conversation approve ${history.conversation?.id ?? '<conversationId>'} ` +
+                `--request ${requestId}${tool}\n` +
+                `or:   cai agent conversation deny ${history.conversation?.id ?? '<conversationId>'} ` +
+                `--request ${requestId}${tool} --message "<reason>"\n`);
+        }
+    }
+};
+export const registerAgent = (program) => {
+    const agent = program
+        .command('agent')
+        .description('Build and test mutable agent drafts, then publish immutable live versions');
+    agent
+        .command('list')
+        .option('--search <text>', 'filter by name')
+        .option('--ownership <mine|shared>', 'ownership filter', 'mine')
+        .description('List agents visible to the current account')
+        .action(async (opts, command) => {
+        const { api } = buildClient(command);
+        const query = new URLSearchParams();
+        if (opts.search)
+            query.set('search', opts.search);
+        if (opts.ownership)
+            query.set('ownership', opts.ownership);
+        const rows = await api.rest(`/agents?${query.toString()}`);
+        emit({ agents: rows ?? [] }, () => printTable(['id', 'name', 'enabled', 'visibility', 'live version id'], (rows ?? []).map(row => [
+            row.id,
+            row.displayName,
+            row.enabled ? 'yes' : 'no',
+            row.visibility,
+            row.liveAgentVersionId ?? '-',
+        ])));
+    });
+    agent
+        .command('get')
+        .argument('<agentId>')
+        .description('Inspect the agent configuration visible to this account and its version status')
+        .action(async (rawId, _opts, command) => {
+        const { api } = buildClient(command);
+        const row = await getAgent(api, parsePositiveId(rawId, 'agentId'));
+        emit({
+            ...row,
+            next: {
+                integrationAction: 'cai integration search <capability>',
+                workflowTool: `cai agent add-workflow ${row.id} --workflow-id <id> --flow <flowId>`,
+            },
+        }, () => printKeyValues([
+            ['id', row.id],
+            ['name', row.displayName],
+            ['enabled', row.enabled ? 'yes' : 'no'],
+            ['visibility', row.visibility],
+            ['live version', row.liveVersion?.versionNumber ?? '(never published)'],
+            ['unpublished changes', row.hasUnpublishedChanges ? 'yes' : 'no'],
+            ['instructions', truncate(row.systemPrompt, 120)],
+        ]));
+    });
+    agent
+        .command('create')
+        .requiredOption('--name <name>', 'agent display name')
+        .option('--instructions <text>', 'agent instructions')
+        .option('--instructions-file <path>', 'read agent instructions from a UTF-8 file')
+        .option('--disabled', 'create the draft disabled', false)
+        .description('Create a private draft agent; nothing becomes live until publish')
+        .action(async (opts, command) => {
+        const { api, config } = buildClient(command);
+        const instructions = instructionText(opts);
+        const row = await api.rest('/agents', {
+            method: 'POST',
+            body: {
+                displayName: opts.name,
+                ...(instructions !== undefined ? { systemPrompt: instructions } : {}),
+                enabled: !opts.disabled,
+            },
+        });
+        const appUrl = agentUrl(config, row.id);
+        emit({ ...row, ...(appUrl ? { appUrl } : {}) }, () => {
+            const pairs = [
+                ['agentId', row.id],
+                ['name', row.displayName],
+                ['state', 'draft — not live'],
+                ['next', 'choose a ready integration action or a workflow tool'],
+                ['ready action', 'cai integration search <capability>'],
+                ['workflow tool', `cai agent add-workflow ${row.id} --workflow-id <id> --flow <flowId>`],
+            ];
+            if (appUrl)
+                pairs.push(['open in app', appUrl]);
+            printKeyValues(pairs);
+        });
+    });
+    agent
+        .command('update')
+        .argument('<agentId>')
+        .option('--name <name>', 'new display name')
+        .option('--instructions <text>', 'new agent instructions')
+        .option('--instructions-file <path>', 'read instructions from a UTF-8 file')
+        .description('Update only the draft; the live agent remains unchanged')
+        .action(async (rawId, opts, command) => {
+        const { api } = buildClient(command);
+        const systemPrompt = instructionText(opts);
+        if (opts.name === undefined && systemPrompt === undefined) {
+            throw userError('Pass --name, --instructions, or --instructions-file.', 'NO_CHANGES');
+        }
+        const agentId = parsePositiveId(rawId, 'agentId');
+        const result = await updateDraft(api, agentId, {
+            ...(opts.name !== undefined ? { displayName: opts.name } : {}),
+            ...(systemPrompt !== undefined ? { systemPrompt } : {}),
+        });
+        emit(result, () => printKeyValues([
+            ['agentId', result.agent.id],
+            ['name', result.agent.displayName],
+            ['state', 'draft updated — live version unchanged'],
+            ['next', `verify Test, then cai agent publish ${agentId}`],
+        ]));
+    });
+    agent
+        .command('visibility')
+        .argument('<agentId>')
+        .requiredOption('--value <private|organization>', 'private revokes organization access; organization shares the published version')
+        .description('Change live agent access (organization requires publishing the agent first; no public mode)')
+        .action(async (rawId, opts, command) => {
+        const visibility = assertAgentVisibility(opts.value);
+        warn(visibility === 'organization'
+            ? 'LIVE ACCESS CHANGE: organization visibility lets active organization members use ' +
+                'the agent’s published version. Publish the agent first; the backend rejects ' +
+                'sharing an unpublished draft. Direct integration actions use the agent owner’s ' +
+                'connected accounts; Controller AI usage comes from the organization’s shared pool.'
+            : 'LIVE ACCESS CHANGE: private visibility revokes organization access and stops ' +
+                'teammates’ active sessions for this agent.');
+        const { api } = buildClient(command);
+        const result = await setAgentVisibility(api, rawId, visibility);
+        emit({ agentId: result.id, visibility: result.visibility, liveAccessChanged: true }, () => printKeyValues([
+            ['agentId', result.id],
+            ['visibility', result.visibility],
+            [
+                'effect',
+                result.visibility === 'organization'
+                    ? 'published version available to organization'
+                    : 'organization access revoked',
+            ],
+        ]));
+    });
+    agent
+        .command('add-workflow')
+        .argument('<agentId>')
+        .requiredOption('--workflow-id <id>', 'workflow containing the tool flow')
+        .requiredOption('--flow <flowId>', 'flow exposed to the agent')
+        .option('--description <text>', 'description the model uses when choosing the tool')
+        .option('--require-confirmation', 'pause every invocation for an explicit user approval before the workflow runs', false)
+        .description('Add a follow-live workflow tool with a backend-generated name to the draft')
+        .action(async (rawId, opts, command) => {
+        const { api } = buildClient(command);
+        const agentId = parsePositiveId(rawId, 'agentId');
+        const result = await updateDraft(api, agentId, {
+            toolOps: [
+                {
+                    op: 'add',
+                    toolType: 'workflow',
+                    workflowId: parsePositiveId(opts.workflowId, 'workflowId'),
+                    flowId: opts.flow,
+                    ...(opts.description !== undefined ? { toolDescription: opts.description } : {}),
+                    // Workflow tools always follow the latest published workflow release.
+                    versionPolicy: 'latest',
+                    requiresConfirmation: Boolean(opts.requireConfirmation),
+                },
+            ],
+        });
+        const added = result.tools.find(tool => tool.workflowId === Number(opts.workflowId) && tool.flowId === opts.flow);
+        emit({ agentId, tool: added ?? null, liveChanged: false }, () => printKeyValues([
+            ['agentId', agentId],
+            ['toolId', added?.id ?? '-'],
+            ['tool', added?.toolName ?? '(generated by backend)'],
+            [
+                'confirmation',
+                added?.requiresConfirmation === true
+                    ? 'required'
+                    : added?.requiresConfirmation === false
+                        ? 'not required'
+                        : 'not returned — verify with `cai agent tools`',
+            ],
+            ['state', 'draft updated — live version unchanged'],
+        ]));
+    });
+    agent
+        .command('add-action')
+        .argument('<agentId>')
+        .requiredOption('--integration <slug>', 'exact slug from `cai integration search`')
+        .requiredOption('--action <key>', 'exact action key from `cai integration actions`')
+        .requiredOption('--connection <id>', 'active connection for this integration')
+        .option('--description <text>', 'when the agent should choose this action')
+        .option('--require-confirmation', 'require approval before each run; default is no approval, so decide for writes or spend', false)
+        .description('Attach one ready integration action to the draft; explicitly review its confirmation policy')
+        .action(async (rawId, opts, command) => {
+        const { api } = buildClient(command);
+        const agentId = parsePositiveId(rawId, 'agentId');
+        const connectionId = parsePositiveId(opts.connection, 'connectionId');
+        const requiresConfirmation = Boolean(opts.requireConfirmation);
+        const result = await updateDraft(api, agentId, {
+            toolOps: [
+                directActionToolOp({
+                    integration: opts.integration,
+                    action: opts.action,
+                    connectionId,
+                    description: opts.description,
+                    requiresConfirmation,
+                }),
+            ],
+        });
+        const added = result.tools.find(tool => tool.toolType === 'pipedream' &&
+            tool.nodeSlug === opts.integration &&
+            tool.nodeComponentKey === opts.action);
+        emit({
+            agentId,
+            tool: added ?? null,
+            liveChanged: false,
+            confirmationReview: confirmationReview(requiresConfirmation),
+        }, () => printKeyValues([
+            ['agentId', agentId],
+            ['toolId', added?.id ?? '-'],
+            ['integration', opts.integration],
+            ['action', opts.action],
+            ['connection', connectionId],
+            ['confirmation', confirmationReview(requiresConfirmation)],
+            ['state', 'draft updated — live version unchanged'],
+        ]));
+    });
+    agent
+        .command('update-tool')
+        .argument('<agentId>')
+        .requiredOption('--tool <toolId>', 'draft tool id')
+        .option('--description <text>', 'new routing description')
+        .option('--connection <id>', 'rebind a ready integration action to another connection')
+        .option('--require-confirmation', 'require approval before every invocation')
+        .option('--no-confirmation', 'run without approval; use only after reviewing writes, messages, deletion, and spend')
+        .description('Update a draft tool; direct-action connection grants are live-bound before republish')
+        .action(async (rawId, opts, command) => {
+        const { api } = buildClient(command);
+        const agentId = parsePositiveId(rawId, 'agentId');
+        const toolId = parsePositiveId(opts.tool, 'toolId');
+        const requiresConfirmation = resolveConfirmationChoice(opts);
+        if (opts.description === undefined &&
+            opts.connection === undefined &&
+            requiresConfirmation === undefined) {
+            throw userError('Pass --description, --connection, --require-confirmation, or --no-confirmation.', 'NO_CHANGES');
+        }
+        const result = await updateDraft(api, agentId, {
+            toolOps: [
+                {
+                    op: 'update',
+                    toolId,
+                    ...(opts.description !== undefined ? { toolDescription: opts.description } : {}),
+                    ...(opts.connection !== undefined
+                        ? { connectionId: parsePositiveId(opts.connection, 'connectionId') }
+                        : {}),
+                    ...(requiresConfirmation !== undefined ? { requiresConfirmation } : {}),
+                },
+            ],
+        });
+        const updated = result.tools.find(tool => tool.id === toolId);
+        const liveAuthorizationChanged = opts.connection !== undefined && updated?.toolType === 'pipedream';
+        emit({
+            agentId,
+            tool: updated ?? null,
+            liveChanged: liveAuthorizationChanged,
+            liveAuthorizationChanged,
+            ...(requiresConfirmation !== undefined
+                ? { confirmationReview: confirmationReview(requiresConfirmation) }
+                : {}),
+        }, () => printKeyValues([
+            ['agentId', agentId],
+            ['toolId', toolId],
+            ['connection', updated?.connectionId ?? opts.connection ?? '-'],
+            [
+                'confirmation',
+                requiresConfirmation === undefined
+                    ? 'unchanged'
+                    : confirmationReview(requiresConfirmation),
+            ],
+            [
+                'state',
+                liveAuthorizationChanged
+                    ? 'draft updated; live action authorization may redirect immediately — publish to version the draft'
+                    : 'draft updated — live version unchanged',
+            ],
+        ]));
+    });
+    agent
+        .command('remove-tool')
+        .argument('<agentId>')
+        .requiredOption('--tool <toolId>', 'draft tool id')
+        .description('Remove a draft tool; direct-action detachment revokes live authorization immediately')
+        .action(async (rawId, opts, command) => {
+        const { api } = buildClient(command);
+        const agentId = parsePositiveId(rawId, 'agentId');
+        const toolId = parsePositiveId(opts.tool, 'toolId');
+        const currentTools = await api.rest(`/agents/${agentId}/tools`);
+        const removed = (currentTools ?? []).find(tool => tool.id === toolId);
+        const result = await updateDraft(api, agentId, { toolOps: [{ op: 'remove', toolId }] });
+        const liveAuthorizationRevoked = removed?.toolType === 'pipedream';
+        emit({
+            agentId,
+            removedToolId: toolId,
+            removedToolType: removed?.toolType ?? null,
+            tools: result.tools,
+            liveChanged: liveAuthorizationRevoked,
+            liveAuthorizationRevoked,
+        }, () => printKeyValues([
+            ['agentId', agentId],
+            ['removed tool', toolId],
+            [
+                'state',
+                liveAuthorizationRevoked
+                    ? 'live action authorization revoked; publish to remove the tool from the live list'
+                    : 'draft updated — live version unchanged',
+            ],
+        ]));
+    });
+    agent
+        .command('add-file')
+        .argument('<agentId>')
+        .requiredOption('--file <path>', 'knowledge file to add to the draft')
+        .option('--name <fileName>', 'name visible to the agent')
+        .option('--type <fileType>', 'txt, md, json, csv, html, or xml')
+        .description('Add a knowledge file to the draft; publish later to freeze it into live')
+        .action(async (rawId, opts, command) => {
+        const { basename, extname } = await import('node:path');
+        const { api } = buildClient(command);
+        const agentId = parsePositiveId(rawId, 'agentId');
+        const fileName = opts.name ?? basename(opts.file);
+        const inferred = extname(fileName).replace(/^\./, '') || 'txt';
+        const result = await updateDraft(api, agentId, {
+            fileOps: [
+                {
+                    op: 'add',
+                    fileName,
+                    fileType: opts.type ?? inferred,
+                    content: readFileSync(opts.file, 'utf8'),
+                },
+            ],
+        });
+        emit({ agentId, files: result.files, liveChanged: false }, () => printKeyValues([
+            ['agentId', agentId],
+            ['file', fileName],
+            ['state', 'draft updated — live version unchanged'],
+        ]));
+    });
+    agent
+        .command('tools')
+        .argument('<agentId>')
+        .description('List owner draft tools or the published projection visible to a shared user')
+        .action(async (rawId, _opts, command) => {
+        const { api } = buildClient(command);
+        const agentId = parsePositiveId(rawId, 'agentId');
+        const tools = await api.rest(`/agents/${agentId}/tools`);
+        emit({ agentId, tools: tools ?? [] }, () => printTable([
+            'id',
+            'type',
+            'name',
+            'integration/workflow',
+            'action/flow',
+            'connection',
+            'tier',
+            'policy',
+            'confirm',
+        ], (tools ?? []).map(tool => [
+            tool.id,
+            tool.toolType,
+            tool.displayName ?? tool.toolName,
+            tool.nodeSlug ?? tool.workflowName ?? tool.workflowId ?? '-',
+            tool.nodeComponentKey ?? tool.flowName ?? tool.flowId ?? '-',
+            tool.connectionId ?? '-',
+            tool.schemaTier ?? '-',
+            tool.versionPolicy ?? '-',
+            tool.requiresConfirmation ? 'required' : 'no',
+        ])));
+    });
+    agent
+        .command('publish-preflight')
+        .argument('<agentId>')
+        .description('Check the agent draft and every attached tool before publishing')
+        .action(async (rawId, _opts, command) => {
+        const { api } = buildClient(command);
+        const agentId = parsePositiveId(rawId, 'agentId');
+        const result = await api.rest(`/agents/${agentId}/publish-preflight`);
+        emit(result, () => printKeyValues([
+            ['agentId', agentId],
+            ['preflight', JSON.stringify(result)],
+        ]));
+    });
+    agent
+        .command('publish')
+        .argument('<agentId>')
+        .option('--name <releaseName>', 'optional release name')
+        .description('Snapshot the draft and move every existing live conversation to the new version')
+        .action(async (rawId, opts, command) => {
+        const { api, config } = buildClient(command);
+        const agentId = parsePositiveId(rawId, 'agentId');
+        const preflight = await api.rest(`/agents/${agentId}/publish-preflight`);
+        if (preflight?.hasBlockers) {
+            throw userError(`Agent publish preflight has blockers:\n${JSON.stringify(preflight, null, 2)}`, 'AGENT_PUBLISH_BLOCKED');
+        }
+        const result = await api.rest(`/agents/${agentId}/publish`, { method: 'POST', body: opts.name ? { name: opts.name } : {} });
+        const appUrl = agentUrl(config, agentId);
+        emit({ agentId, ...result, ...(appUrl ? { appUrl } : {}) }, () => {
+            const pairs = [
+                ['agentId', agentId],
+                ['live version', result.versionNumber],
+                ['version id', result.agentVersionId],
+                ['effect', 'existing live conversations moved to this version'],
+            ];
+            if (appUrl)
+                pairs.push(['open in app', appUrl]);
+            printKeyValues(pairs);
+        });
+    });
+    agent
+        .command('versions')
+        .argument('<agentId>')
+        .description('List immutable published versions')
+        .action(async (rawId, _opts, command) => {
+        const { api } = buildClient(command);
+        const agentId = parsePositiveId(rawId, 'agentId');
+        const versions = await api.rest(`/agents/${agentId}/versions`);
+        emit({ agentId, versions: versions ?? [] }, () => printTable(['version', 'name', 'live', 'created'], (versions ?? []).map(version => [
+            version.versionNumber,
+            version.name ?? '-',
+            version.isLive ? 'yes' : '',
+            version.createdAt,
+        ])));
+    });
+    const conversation = agent
+        .command('conversation')
+        .description('Verify owner-only Test/draft or latest-published Live agent conversations');
+    conversation
+        .command('list')
+        .argument('<agentId>')
+        .option('--mode <dev|live>', 'filter to the draft or live rail')
+        .description('List verification conversations for an agent')
+        .action(async (rawId, opts, command) => {
+        if (opts.mode && !['dev', 'live'].includes(opts.mode)) {
+            throw userError('--mode must be dev or live.', 'BAD_CONVERSATION_MODE');
+        }
+        const { api } = buildClient(command);
+        const agentId = parsePositiveId(rawId, 'agentId');
+        const query = opts.mode ? `?mode=${encodeURIComponent(opts.mode)}` : '';
+        const result = await api.rest(`/agents/${agentId}/conversations${query}`);
+        emit(result, () => printTable(['id', 'rail', 'version', 'status', 'title', 'updated'], (result.conversations ?? []).map(row => [
+            row.id,
+            row.isDraft ? 'draft' : 'live',
+            row.agentVersionNumber ?? row.agentVersionId ?? '-',
+            row.status,
+            row.title ?? '-',
+            row.updatedAt ?? '-',
+        ])));
+    });
+    conversation
+        .command('create')
+        .argument('<agentId>')
+        .option('--draft', 'owner-only Test: current agent draft and workflow development heads')
+        .option('--live', 'Live: latest published agent and workflow releases (default)')
+        .option('--title <title>', 'conversation title')
+        .option('--model <model>', 'runtime model override')
+        .description('Create a conversation on an explicit agent rail')
+        .action(async (rawId, opts, command) => {
+        const { api, config } = buildClient(command);
+        const agentId = parsePositiveId(rawId, 'agentId');
+        const draft = selectedDraftMode(opts, false);
+        const row = await api.rest(`/agents/${agentId}/conversations`, {
+            method: 'POST',
+            body: {
+                draft,
+                ...(opts.title !== undefined ? { title: opts.title } : {}),
+                ...(opts.model ? { model: opts.model } : {}),
+            },
+        });
+        assertConversationRail(row, draft);
+        const appUrl = conversationUrl(config, agentId, row.id);
+        emit({ ...row, ...(appUrl ? { appUrl } : {}) }, () => printConversation(row, appUrl));
+    });
+    conversation
+        .command('status')
+        .argument('<conversationId>')
+        .description('Read the conversation rail, adopted version, model, and status')
+        .action(async (rawId, _opts, command) => {
+        const { api } = buildClient(command);
+        const conversationId = parsePositiveId(rawId, 'conversationId');
+        const row = await api.rest(`/agent-conversations/${conversationId}`);
+        emit(row, () => printConversation(row));
+    });
+    conversation
+        .command('history')
+        .argument('<conversationId>')
+        .description('Read persisted messages, events, and pending permission requests')
+        .action(async (rawId, _opts, command) => {
+        const { api } = buildClient(command);
+        const conversationId = parsePositiveId(rawId, 'conversationId');
+        const history = await api.rest(`/agent-conversations/${conversationId}/history`);
+        emit(history, () => printHistory(history));
+    });
+    conversation
+        .command('approve')
+        .argument('<conversationId>')
+        .requiredOption('--request <requestId>', 'exact requestId from conversation history')
+        .option('--tool <toolName>', 'exact toolName from the pending request, when present')
+        .description('Approve one pending tool request and resume the active conversation')
+        .action(async (rawId, opts, command) => {
+        const { api } = buildClient(command);
+        const result = await respondAgentPermission(api, rawId, opts.request, 'allow', {
+            toolName: opts.tool,
+        });
+        emit({ conversationId: Number(rawId), requestId: opts.request, behavior: 'allow', ...result }, () => printKeyValues([
+            ['conversationId', rawId],
+            ['requestId', opts.request],
+            ['decision', 'approved — conversation resumed'],
+            ['next', `cai agent conversation history ${rawId}`],
+        ]));
+    });
+    conversation
+        .command('deny')
+        .argument('<conversationId>')
+        .requiredOption('--request <requestId>', 'exact requestId from conversation history')
+        .option('--tool <toolName>', 'exact toolName from the pending request, when present')
+        .option('--message <reason>', 'reason returned to the agent')
+        .description('Deny one pending tool request and resume the active conversation')
+        .action(async (rawId, opts, command) => {
+        const { api } = buildClient(command);
+        const result = await respondAgentPermission(api, rawId, opts.request, 'deny', {
+            toolName: opts.tool,
+            message: opts.message,
+        });
+        emit({ conversationId: Number(rawId), requestId: opts.request, behavior: 'deny', ...result }, () => printKeyValues([
+            ['conversationId', rawId],
+            ['requestId', opts.request],
+            ['decision', 'denied — conversation resumed'],
+            ['next', `cai agent conversation history ${rawId}`],
+        ]));
+    });
+    conversation
+        .command('send')
+        .argument('<conversationId>')
+        .requiredOption('--message <text>', 'message to send')
+        .option('--wait', 'wait for the next completed persisted assistant reply', false)
+        .option('--timeout <seconds>', 'reply wait budget', '120')
+        .description('Send a message, optionally waiting for a verifiable persisted reply')
+        .action(async (rawId, opts, command) => {
+        const { api } = buildClient(command);
+        const conversationId = parsePositiveId(rawId, 'conversationId');
+        // Validate the wait budget BEFORE the message is posted: failing after
+        // the POST makes a retry send the message twice.
+        const timeoutSeconds = opts.wait ? parseSeconds(opts.timeout, '--timeout') : null;
+        const before = await api.rest(`/agent-conversations/${conversationId}/history`);
+        const afterMessageId = Math.max(0, ...(before.messages ?? []).map(message => message.id));
+        const afterEventId = Math.max(0, ...(before.events ?? []).map(event => event.id));
+        const accepted = await api.rest(`/agent-conversations/${conversationId}/send-message`, { method: 'POST', body: { message: opts.message } });
+        if (!opts.wait) {
+            emit({ conversationId, accepted: accepted.success }, () => printKeyValues([
+                ['conversationId', conversationId],
+                ['accepted', accepted.success ? 'yes' : 'no'],
+                ['next', `cai agent conversation history ${conversationId}`],
+            ]));
+            return;
+        }
+        const result = await pollAgentReply(api, conversationId, afterMessageId, afterEventId, (timeoutSeconds ?? 120) * 1_000);
+        const reply = requireReply(result, conversationId);
+        emit({ conversationId, accepted: true, reply, history: result.history }, () => printKeyValues([
+            ['conversationId', conversationId],
+            ['verified reply', contentText(reply.content)],
+            ['cost USD', reply.totalCostUsd ?? '-'],
+        ]));
+    });
+    agent
+        .command('test')
+        .argument('<agentId>')
+        .requiredOption('--message <text>', 'verification prompt')
+        .option('--draft', 'owner-only Test: current agent draft and workflow development heads (default)')
+        .option('--live', 'Live: latest published agent and workflow releases')
+        .option('--title <title>', 'conversation title', 'CLI verification')
+        .option('--model <model>', 'runtime model override')
+        .option('--timeout <seconds>', 'reply wait budget', '120')
+        .description('Create, send, and verify one persisted reply on an explicit agent rail')
+        .action(async (rawId, opts, command) => {
+        const { api, config } = buildClient(command);
+        const agentId = parsePositiveId(rawId, 'agentId');
+        const draft = selectedDraftMode(opts, true);
+        const timeoutSeconds = parseSeconds(opts.timeout, '--timeout');
+        const row = await api.rest(`/agents/${agentId}/conversations`, {
+            method: 'POST',
+            body: {
+                draft,
+                title: opts.title,
+                ...(opts.model ? { model: opts.model } : {}),
+            },
+        });
+        assertConversationRail(row, draft);
+        await api.rest(`/agent-conversations/${row.id}/send-message`, {
+            method: 'POST',
+            body: { message: opts.message },
+        });
+        const result = await pollAgentReply(api, row.id, 0, 0, timeoutSeconds * 1_000);
+        const reply = requireReply(result, row.id);
+        const appUrl = conversationUrl(config, agentId, row.id);
+        emit({
+            verified: true,
+            rail: draft ? 'draft' : 'live',
+            agentId,
+            ...(appUrl ? { appUrl } : {}),
+            conversation: row,
+            reply,
+            history: result.history,
+        }, () => {
+            printConversation(row, appUrl);
+            process.stdout.write('\nverification\n');
+            printKeyValues([
+                ['verified', 'yes'],
+                ['reply', contentText(reply.content)],
+                ['cost USD', reply.totalCostUsd ?? '-'],
+            ]);
+        });
+    });
+};
+//# sourceMappingURL=agent.js.map