@agentuity/cli 0.1.16 → 0.1.17

package/src/cmd/cloud/queue/get.ts

@@ -0,0 +1,158 @@
+import { z } from 'zod';
+import { createCommand } from '../../../types';
+import * as tui from '../../../tui';
+import { createQueueAPIClient, getQueueApiOptions } from './util';
+import { getCommand } from '../../../command-prefix';
+import { getQueue, getMessage, QueueSchema, MessageSchema, type Message } from '@agentuity/server';
+
+const GetResponseSchema = z.union([
+	z.object({ type: z.literal('queue'), queue: QueueSchema }),
+	z.object({ type: z.literal('message'), message: MessageSchema }),
+]);
+
+function displayMessage(message: Message): void {
+	const details: Record<string, unknown> = {
+		ID: message.id,
+		'Queue ID': message.queue_id,
+		Offset: message.offset,
+		State: message.state,
+		'Delivery Attempts': message.delivery_attempts,
+	};
+
+	if (message.partition_key) {
+		details['Partition Key'] = message.partition_key;
+	}
+	if (message.idempotency_key) {
+		details['Idempotency Key'] = message.idempotency_key;
+	}
+
+	details.Published = message.published_at ? new Date(message.published_at).toLocaleString() : '-';
+	details.Created = message.created_at ? new Date(message.created_at).toLocaleString() : '-';
+
+	if (message.expires_at) {
+		details.Expires = new Date(message.expires_at).toLocaleString();
+	}
+	if (message.delivered_at) {
+		details.Delivered = new Date(message.delivered_at).toLocaleString();
+	}
+	if (message.acknowledged_at) {
+		details.Acknowledged = new Date(message.acknowledged_at).toLocaleString();
+	}
+
+	tui.table([details], undefined, { layout: 'vertical' });
+
+	tui.newline();
+	tui.info('Payload');
+	tui.json(message.payload);
+
+	if (message.metadata && Object.keys(message.metadata).length > 0) {
+		tui.newline();
+		tui.info('Metadata');
+		tui.json(message.metadata);
+	}
+}
+
+export const getSubcommand = createCommand({
+	name: 'get',
+	description: 'Get queue or message details',
+	tags: ['read-only', 'fast', 'requires-auth'],
+	requires: { auth: true },
+	examples: [
+		{ command: getCommand('cloud queue get my-queue'), description: 'Get queue details' },
+		{
+			command: getCommand('cloud queue get my-queue msg_abc123'),
+			description: 'Get message details',
+		},
+	],
+	schema: {
+		args: z.object({
+			queue_name: z.string().min(1).describe('Queue name'),
+			message_id: z.string().optional().describe('Message ID (msg_...) to get message details'),
+		}),
+		response: GetResponseSchema,
+	},
+	idempotent: true,
+
+	async handler(ctx) {
+		const { args, options } = ctx;
+		const client = await createQueueAPIClient(ctx);
+		const apiOptions = getQueueApiOptions(ctx);
+
+		if (args.message_id) {
+			const message = await getMessage(client, args.queue_name, args.message_id, apiOptions);
+
+			if (!options.json) {
+				displayMessage(message);
+			}
+
+			return { type: 'message' as const, message };
+		}
+
+		const queue = await getQueue(client, args.queue_name, apiOptions);
+
+		if (!options.json) {
+			const details: Record<string, unknown> = {
+				Name: queue.name,
+				ID: queue.id,
+				Type: queue.queue_type,
+			};
+
+			if (queue.description) {
+				details.Description = queue.description;
+			}
+
+			if (queue.paused_at) {
+				details.Status = 'Paused';
+				details['Paused At'] = new Date(queue.paused_at).toLocaleString();
+			} else {
+				details.Status = 'Active';
+			}
+
+			details.Created = new Date(queue.created_at).toLocaleString();
+			details.Updated = new Date(queue.updated_at).toLocaleString();
+
+			tui.table([details], undefined, { layout: 'vertical' });
+
+			if (
+				queue.message_count !== undefined ||
+				queue.dlq_count !== undefined ||
+				queue.next_offset !== undefined
+			) {
+				tui.newline();
+				tui.info('Stats');
+				tui.table(
+					[
+						{
+							Messages: queue.message_count ?? 0,
+							'DLQ Count': queue.dlq_count ?? 0,
+							'Next Offset': queue.next_offset ?? 0,
+						},
+					],
+					undefined,
+					{ layout: 'vertical' }
+				);
+			}
+
+			if (queue.default_visibility_timeout_seconds !== undefined) {
+				tui.newline();
+				tui.info('Settings');
+				const settings: Record<string, unknown> = {};
+				if (queue.default_ttl_seconds != null) {
+					settings['Default TTL'] = `${queue.default_ttl_seconds}s`;
+				}
+				settings['Visibility Timeout'] = `${queue.default_visibility_timeout_seconds}s`;
+				settings['Max Retries'] = queue.default_max_retries;
+				settings['Retry Backoff'] = `${queue.default_retry_backoff_ms}ms`;
+				settings['Max Backoff'] = `${queue.default_retry_max_backoff_ms}ms`;
+				settings['Backoff Multiplier'] = `${queue.default_retry_multiplier}x`;
+				settings['Max In-Flight'] = queue.max_in_flight_per_client;
+
+				tui.table([settings], undefined, { layout: 'vertical' });
+			}
+		}
+
+		return { type: 'queue' as const, queue };
+	},
+});
+
+export default getSubcommand;

package/src/cmd/cloud/queue/index.ts

@@ -0,0 +1,66 @@
+import { createCommand } from '../../../types';
+import { listSubcommand } from './list';
+import { createSubcommand } from './create';
+import { getSubcommand } from './get';
+import { deleteSubcommand } from './delete';
+import { publishSubcommand } from './publish';
+import { messagesSubcommand } from './messages';
+import { receiveSubcommand } from './receive';
+import { ackSubcommand } from './ack';
+import { nackSubcommand } from './nack';
+import { dlqSubcommand } from './dlq';
+import { destinationsSubcommand } from './destinations';
+import { sourcesSubcommand } from './sources';
+import { pauseSubcommand } from './pause';
+import { resumeSubcommand } from './resume';
+import { statsSubcommand } from './stats';
+import { getCommand } from '../../../command-prefix';
+
+export const command = createCommand({
+	name: 'queue',
+	aliases: ['queues'],
+	description: 'Manage message queues',
+	tags: ['requires-auth'],
+	examples: [
+		{
+			command: getCommand('cloud queue list'),
+			description: 'List all queues',
+		},
+		{
+			command: getCommand('cloud queue create worker --name my-tasks'),
+			description: 'Create a worker queue',
+		},
+		{
+			command: getCommand('cloud queue publish my-queue \'{"task":"process"}\''),
+			description: 'Publish a message',
+		},
+		{
+			command: getCommand('cloud queue receive my-queue'),
+			description: 'Receive a message from a worker queue',
+		},
+		{
+			command: getCommand('cloud queue stats'),
+			description: 'View analytics for all queues',
+		},
+	],
+	subcommands: [
+		listSubcommand,
+		createSubcommand,
+		getSubcommand,
+		deleteSubcommand,
+		publishSubcommand,
+		messagesSubcommand,
+		receiveSubcommand,
+		ackSubcommand,
+		nackSubcommand,
+		dlqSubcommand,
+		destinationsSubcommand,
+		sourcesSubcommand,
+		pauseSubcommand,
+		resumeSubcommand,
+		statsSubcommand,
+	],
+	requires: { auth: true },
+});
+
+export default command;

package/src/cmd/cloud/queue/list.ts

@@ -0,0 +1,81 @@
+import { z } from 'zod';
+import { createCommand } from '../../../types';
+import * as tui from '../../../tui';
+import { createQueueAPIClient, getQueueApiOptions } from './util';
+import { getCommand } from '../../../command-prefix';
+import { listQueues, type Queue } from '@agentuity/server';
+
+const QueueListResponseSchema = z.object({
+	queues: z.array(
+		z.object({
+			name: z.string(),
+			queue_type: z.string(),
+			message_count: z.number(),
+			dlq_count: z.number(),
+			created_at: z.string(),
+		})
+	),
+	total: z.number().optional(),
+});
+
+export const listSubcommand = createCommand({
+	name: 'list',
+	aliases: ['ls'],
+	description: 'List all queues',
+	tags: ['read-only', 'fast', 'requires-auth'],
+	requires: { auth: true },
+	examples: [
+		{ command: getCommand('cloud queue list'), description: 'List all queues' },
+		{ command: getCommand('cloud queue ls'), description: 'List all queues (alias)' },
+	],
+	schema: {
+		args: z.object({}),
+		options: z.object({
+			limit: z.coerce.number().optional().describe('Maximum number of queues to return'),
+			offset: z.coerce.number().optional().describe('Offset for pagination'),
+		}),
+		response: QueueListResponseSchema,
+	},
+	idempotent: true,
+
+	async handler(ctx) {
+		const { options, opts } = ctx;
+		const client = await createQueueAPIClient(ctx);
+		const result = await listQueues(
+			client,
+			{
+				limit: opts.limit,
+				offset: opts.offset,
+			},
+			getQueueApiOptions(ctx)
+		);
+
+		if (!options.json) {
+			if (result.queues.length === 0) {
+				tui.info('No queues found');
+			} else {
+				const tableData = result.queues.map((q: Queue) => ({
+					Name: q.name,
+					Type: q.queue_type,
+					Messages: q.message_count ?? 0,
+					DLQ: q.dlq_count ?? 0,
+					Created: new Date(q.created_at).toLocaleString(),
+				}));
+				tui.table(tableData, ['Name', 'Type', 'Messages', 'DLQ', 'Created']);
+			}
+		}
+
+		return {
+			queues: result.queues.map((q: Queue) => ({
+				name: q.name,
+				queue_type: q.queue_type,
+				message_count: q.message_count ?? 0,
+				dlq_count: q.dlq_count ?? 0,
+				created_at: q.created_at,
+			})),
+			total: result.total,
+		};
+	},
+});
+
+export default listSubcommand;

package/src/cmd/cloud/queue/messages.ts

@@ -0,0 +1,160 @@
+import { z } from 'zod';
+import { createCommand } from '../../../types';
+import * as tui from '../../../tui';
+import { createQueueAPIClient, getQueueApiOptions } from './util';
+import { getCommand } from '../../../command-prefix';
+import { listMessages, getMessage, MessageSchema, type Message } from '@agentuity/server';
+
+const MessagesListResponseSchema = z.object({
+	messages: z.array(
+		z.object({
+			id: z.string(),
+			offset: z.number(),
+			state: z.string().optional(),
+			size: z.number().optional(),
+			created_at: z.string().optional(),
+		})
+	),
+	total: z.number().optional(),
+});
+
+const MessagesResponseSchema = z.union([
+	z.object({ type: z.literal('list'), data: MessagesListResponseSchema }),
+	z.object({ type: z.literal('message'), message: MessageSchema }),
+]);
+
+function displayMessage(message: Message): void {
+	const details: Record<string, unknown> = {
+		ID: message.id,
+		'Queue ID': message.queue_id,
+		Offset: message.offset,
+		State: message.state,
+		'Delivery Attempts': message.delivery_attempts,
+	};
+
+	if (message.partition_key) {
+		details['Partition Key'] = message.partition_key;
+	}
+	if (message.idempotency_key) {
+		details['Idempotency Key'] = message.idempotency_key;
+	}
+
+	details.Published = message.published_at ? new Date(message.published_at).toLocaleString() : '-';
+	details.Created = message.created_at ? new Date(message.created_at).toLocaleString() : '-';
+
+	if (message.expires_at) {
+		details.Expires = new Date(message.expires_at).toLocaleString();
+	}
+	if (message.delivered_at) {
+		details.Delivered = new Date(message.delivered_at).toLocaleString();
+	}
+	if (message.acknowledged_at) {
+		details.Acknowledged = new Date(message.acknowledged_at).toLocaleString();
+	}
+
+	tui.table([details], undefined, { layout: 'vertical' });
+
+	tui.newline();
+	tui.info('Payload');
+	tui.json(message.payload);
+
+	if (message.metadata && Object.keys(message.metadata).length > 0) {
+		tui.newline();
+		tui.info('Metadata');
+		tui.json(message.metadata);
+	}
+}
+
+export const messagesSubcommand = createCommand({
+	name: 'messages',
+	aliases: ['msgs'],
+	description: 'List messages in a queue or get a specific message',
+	tags: ['read-only', 'fast', 'requires-auth'],
+	requires: { auth: true },
+	examples: [
+		{
+			command: getCommand('cloud queue messages my-queue'),
+			description: 'List messages in a queue',
+		},
+		{
+			command: getCommand('cloud queue messages my-queue --limit 10'),
+			description: 'List first 10 messages',
+		},
+		{
+			command: getCommand('cloud queue messages my-queue msg_abc123'),
+			description: 'Get a specific message by ID',
+		},
+	],
+	schema: {
+		args: z.object({
+			queue_name: z.string().min(1).describe('Queue name'),
+			message_id: z
+				.string()
+				.optional()
+				.describe('Message ID (optional, to get a specific message)'),
+		}),
+		options: z.object({
+			limit: z.number().optional().describe('Maximum number of messages to return'),
+			offset: z.number().optional().describe('Offset for pagination'),
+		}),
+		response: MessagesResponseSchema,
+	},
+	idempotent: true,
+
+	async handler(ctx) {
+		const { args, opts, options } = ctx;
+		const client = await createQueueAPIClient(ctx);
+		const apiOptions = getQueueApiOptions(ctx);
+
+		if (args.message_id) {
+			const message = await getMessage(client, args.queue_name, args.message_id, apiOptions);
+
+			if (!options.json) {
+				displayMessage(message);
+			}
+
+			return { type: 'message' as const, message };
+		}
+
+		const result = await listMessages(
+			client,
+			args.queue_name,
+			{
+				limit: opts.limit,
+				offset: opts.offset,
+			},
+			apiOptions
+		);
+
+		if (!options.json) {
+			if (result.messages.length === 0) {
+				tui.info('No messages found');
+			} else {
+				const tableData = result.messages.map((m: Message) => ({
+					ID: m.id,
+					Offset: m.offset,
+					State: m.state,
+					Size: m.size,
+					Created: m.created_at ? new Date(m.created_at).toLocaleString() : 'N/A',
+				}));
+				tui.table(tableData, ['ID', 'Offset', 'State', 'Size', 'Created']);
+			}
+		}
+
+		return {
+			type: 'list' as const,
+			data: {
+				messages: result.messages.map((m: Message) => ({
+					id: m.id,
+					offset: m.offset,
+					state: m.state,
+					size: m.size,
+					created_at: m.created_at,
+				})),
+				total: result.total,
+			},
+		};
+	},
+});
+
+export default messagesSubcommand;

package/src/cmd/cloud/queue/nack.ts

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+import { createCommand } from '../../../types';
+import * as tui from '../../../tui';
+import { createQueueAPIClient, getQueueApiOptions } from './util';
+import { getCommand } from '../../../command-prefix';
+import { nackMessage } from '@agentuity/server';
+
+const NackResponseSchema = z.object({
+	success: z.boolean(),
+	queue_name: z.string(),
+	message_id: z.string(),
+});
+
+export const nackSubcommand = createCommand({
+	name: 'nack',
+	description: 'Negative acknowledge a message (return to queue for retry)',
+	tags: ['mutating', 'updates-resource', 'requires-auth'],
+	requires: { auth: true },
+	examples: [
+		{
+			command: getCommand('cloud queue nack my-queue msg-123'),
+			description: 'Return message to queue for retry',
+		},
+	],
+	schema: {
+		args: z.object({
+			queue_name: z.string().min(1).describe('Queue name'),
+			message_id: z.string().min(1).describe('Message ID'),
+		}),
+		response: NackResponseSchema,
+	},
+
+	async handler(ctx) {
+		const { args, options } = ctx;
+		const client = await createQueueAPIClient(ctx);
+		await nackMessage(client, args.queue_name, args.message_id, getQueueApiOptions(ctx));
+
+		if (!options.json) {
+			tui.success(`Returned message to queue: ${args.message_id}`);
+		}
+
+		return {
+			success: true,
+			queue_name: args.queue_name,
+			message_id: args.message_id,
+		};
+	},
+});
+
+export default nackSubcommand;

package/src/cmd/cloud/queue/pause.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+import { createCommand } from '../../../types';
+import * as tui from '../../../tui';
+import { createQueueAPIClient, getQueueApiOptions } from './util';
+import { getCommand } from '../../../command-prefix';
+import { pauseQueue, QueueSchema } from '@agentuity/server';
+
+export const pauseSubcommand = createCommand({
+	name: 'pause',
+	description: 'Pause message delivery for a queue',
+	tags: ['mutating', 'updates-resource', 'requires-auth'],
+	requires: { auth: true },
+	examples: [
+		{
+			command: getCommand('cloud queue pause my-queue'),
+			description: 'Pause a queue',
+		},
+	],
+	schema: {
+		args: z.object({
+			name: z.string().min(1).describe('Queue name'),
+		}),
+		response: QueueSchema,
+	},
+
+	async handler(ctx) {
+		const { args, options } = ctx;
+		const client = await createQueueAPIClient(ctx);
+
+		const queue = await pauseQueue(client, args.name, getQueueApiOptions(ctx));
+
+		if (!options.json) {
+			tui.success(`Paused queue: ${queue.name}`);
+			tui.info(`  Paused at: ${queue.paused_at}`);
+		}
+
+		return queue;
+	},
+});
+
+export default pauseSubcommand;

package/src/cmd/cloud/queue/publish.ts

@@ -0,0 +1,88 @@
+import { z } from 'zod';
+import { createCommand } from '../../../types';
+import * as tui from '../../../tui';
+import { createQueueAPIClient, getQueueApiOptions } from './util';
+import { getCommand } from '../../../command-prefix';
+import { publishMessage, MessageSchema } from '@agentuity/server';
+import { ErrorCode } from '../../../errors';
+
+export const publishSubcommand = createCommand({
+	name: 'publish',
+	aliases: ['pub', 'send'],
+	description: 'Publish a message to a queue',
+	tags: ['mutating', 'creates-resource', 'requires-auth'],
+	requires: { auth: true },
+	examples: [
+		{
+			command: getCommand('cloud queue publish my-queue \'{"task":"process"}\''),
+			description: 'Publish a JSON message',
+		},
+		{
+			command: getCommand(
+				'cloud queue publish my-queue \'{"task":"process"}\' --metadata \'{"priority":"high"}\''
+			),
+			description: 'Publish with metadata',
+		},
+		{
+			command: getCommand('cloud queue publish my-queue "hello" --ttl 3600'),
+			description: 'Publish with 1h TTL',
+		},
+	],
+	schema: {
+		args: z.object({
+			queue_name: z.string().min(1).describe('Queue name'),
+			payload: z.string().min(1).describe('Message payload (JSON)'),
+		}),
+		options: z.object({
+			metadata: z.string().optional().describe('Message metadata as JSON'),
+			partitionKey: z.string().optional().describe('Partition key for ordering'),
+			idempotencyKey: z.string().optional().describe('Idempotency key to prevent duplicates'),
+			ttl: z.coerce.number().optional().describe('Message TTL in seconds'),
+		}),
+		response: MessageSchema,
+	},
+
+	async handler(ctx) {
+		const { args, opts, options } = ctx;
+		const client = await createQueueAPIClient(ctx);
+
+		let payload: unknown;
+		try {
+			payload = JSON.parse(args.payload);
+		} catch {
+			tui.fatal('Invalid payload JSON', ErrorCode.INVALID_ARGUMENT);
+		}
+
+		let metadata: Record<string, unknown> | undefined;
+		if (opts.metadata) {
+			try {
+				metadata = JSON.parse(opts.metadata);
+			} catch {
+				tui.fatal('Invalid metadata JSON', ErrorCode.INVALID_ARGUMENT);
+			}
+		}
+
+		const message = await publishMessage(
+			client,
+			args.queue_name,
+			{
+				payload,
+				metadata,
+				partition_key: opts.partitionKey,
+				idempotency_key: opts.idempotencyKey,
+				ttl_seconds: opts.ttl,
+			},
+			getQueueApiOptions(ctx)
+		);
+
+		if (!options.json) {
+			tui.success(`Published message: ${message.id}`);
+			console.log(`  Offset: ${message.offset}`);
+			console.log(`  State:  ${message.state}`);
+		}
+
+		return message;
+	},
+});
+
+export default publishSubcommand;