@agentuity/cli 1.0.22 → 1.0.24

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

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+import { createCommand } from '../../../types';
+import * as tui from '../../../tui';
+import { createEmailAdapter, EmailAddressSchema } from './util';
+
+export const listSubcommand = createCommand({
+	name: 'list',
+	aliases: ['ls'],
+	description: 'List email addresses',
+	tags: ['read-only', 'requires-auth'],
+	requires: { auth: true },
+	schema: {
+		response: z.array(EmailAddressSchema),
+	},
+
+	async handler(ctx) {
+		const { options } = ctx;
+		const email = await createEmailAdapter(ctx);
+		const addresses = await email.listAddresses();
+
+		if (!options.json) {
+			tui.table(
+				addresses.map((item) => ({
+					ID: item.id,
+					Email: item.email,
+					Project: item.project_id ?? '-',
+					Provider: item.provider ?? '-',
+					Created: new Date(item.created_at).toLocaleString(),
+				})),
+				[
+					{ name: 'ID', alignment: 'left' },
+					{ name: 'Email', alignment: 'left' },
+					{ name: 'Project', alignment: 'left' },
+					{ name: 'Provider', alignment: 'left' },
+					{ name: 'Created', alignment: 'left' },
+				]
+			);
+		}
+
+		return addresses.map((item) => ({
+			id: item.id,
+			email: item.email,
+			project_id: item.project_id,
+			provider: item.provider,
+			created_at: item.created_at,
+			updated_at: item.updated_at,
+		}));
+	},
+});
+
+export default listSubcommand;

package/src/cmd/cloud/email/outbound/get.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+import { createCommand } from '../../../../types';
+import * as tui from '../../../../tui';
+import { createEmailAdapter, truncate } from '../util';
+import { EmailOutboundSchema } from './schemas';
+
+export const getSubcommand = createCommand({
+	name: 'get',
+	description: 'Get a sent email by ID',
+	tags: ['read-only', 'requires-auth'],
+	requires: { auth: true },
+	schema: {
+		args: z.object({
+			id: z.string().min(1).describe('Outbound email ID (eout_*)'),
+		}),
+		response: EmailOutboundSchema,
+	},
+
+	async handler(ctx) {
+		const { args, options } = ctx;
+		const email = await createEmailAdapter(ctx);
+		const outbound = await email.getOutbound(args.id);
+
+		if (!outbound) {
+			tui.fatal(`Outbound email not found: ${args.id}`);
+		}
+
+		if (!options.json) {
+			tui.success(`Outbound Email: ${tui.bold(outbound.id)}`);
+			tui.table(
+				[
+					{
+						ID: outbound.id,
+						From: outbound.from,
+						To: outbound.to,
+						Subject: outbound.subject ?? '-',
+						Text: truncate(outbound.text),
+						Status: outbound.status ?? '-',
+						Error: outbound.error ?? '-',
+						Created: outbound.created_at
+							? new Date(outbound.created_at).toLocaleString()
+							: '-',
+					},
+				],
+				['ID', 'From', 'To', 'Subject', 'Text', 'Status', 'Error', 'Created'],
+				{ layout: 'vertical', padStart: '  ' }
+			);
+		}
+
+		return outbound;
+	},
+});
+
+export default getSubcommand;

package/src/cmd/cloud/email/outbound/index.ts

@@ -0,0 +1,13 @@
+import { createCommand } from '../../../../types';
+import { listSubcommand } from './list';
+import { getSubcommand } from './get';
+
+export const outboundCommand = createCommand({
+	name: 'outbound',
+	description: 'Manage outbound (sent) emails',
+	tags: ['requires-auth'],
+	requires: { auth: true },
+	subcommands: [listSubcommand, getSubcommand],
+});
+
+export default outboundCommand;

package/src/cmd/cloud/email/outbound/list.ts

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+import { createCommand } from '../../../../types';
+import * as tui from '../../../../tui';
+import { createEmailAdapter } from '../util';
+import { EmailOutboundSchema } from './schemas';
+
+export const listSubcommand = createCommand({
+	name: 'list',
+	aliases: ['ls'],
+	description: 'List sent emails',
+	tags: ['read-only', 'requires-auth'],
+	requires: { auth: true },
+	schema: {
+		options: z.object({
+			addressId: z.string().optional().describe('Filter by email address ID'),
+		}),
+		response: z.array(EmailOutboundSchema),
+	},
+
+	async handler(ctx) {
+		const { opts, options } = ctx;
+		const email = await createEmailAdapter(ctx);
+		const outbound = await email.listOutbound(opts.addressId);
+
+		if (!options.json) {
+			tui.table(
+				outbound.map((item) => ({
+					ID: item.id,
+					From: item.from,
+					To: item.to,
+					Subject: item.subject ?? '-',
+					Status: item.status ?? '-',
+					Created: item.created_at ? new Date(item.created_at).toLocaleString() : '-',
+				})),
+				[
+					{ name: 'ID', alignment: 'left' },
+					{ name: 'From', alignment: 'left' },
+					{ name: 'To', alignment: 'left' },
+					{ name: 'Subject', alignment: 'left' },
+					{ name: 'Status', alignment: 'left' },
+					{ name: 'Created', alignment: 'left' },
+				]
+			);
+		}
+
+		return outbound;
+	},
+});
+
+export default listSubcommand;

package/src/cmd/cloud/email/outbound/schemas.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+
+export const EmailOutboundSchema = z.object({
+	id: z.string(),
+	from: z.string(),
+	to: z.string(),
+	subject: z.string().optional(),
+	text: z.string().optional(),
+	html: z.string().optional(),
+	status: z.string().optional(),
+	error: z.string().optional(),
+	created_at: z.string().optional(),
+	headers: z.record(z.string(), z.unknown()).optional(),
+	attachments: z.array(z.unknown()).optional(),
+});

package/src/cmd/cloud/email/send.ts

@@ -0,0 +1,89 @@
+import { basename } from 'node:path';
+import { z } from 'zod';
+import type { EmailAttachment } from '@agentuity/core';
+import { createCommand } from '../../../types';
+import * as tui from '../../../tui';
+import { createEmailAdapter, truncate } from './util';
+import { EmailOutboundSchema } from './outbound/schemas';
+
+export const sendSubcommand = createCommand({
+	name: 'send',
+	description: 'Send an email',
+	tags: ['mutating', 'requires-auth'],
+	requires: { auth: true },
+	schema: {
+		args: z.object({
+			to: z.string().email().describe('Destination email address'),
+		}),
+		options: z.object({
+			from: z.string().email().describe('Sender email address (must be owned by org)'),
+			subject: z.string().min(1).describe('Email subject'),
+			text: z.string().optional().describe('Plain text body'),
+			html: z.string().optional().describe('HTML body'),
+			file: z.array(z.string()).optional().describe('Attachment file path (repeatable)'),
+		}),
+		response: EmailOutboundSchema,
+	},
+
+	async handler(ctx) {
+		const { args, opts, options } = ctx;
+
+		if (!opts.text && !opts.html) {
+			tui.fatal('At least one of --text or --html is required');
+		}
+
+		const fileValues = Array.isArray(opts.file)
+			? opts.file
+			: opts.file
+				? [opts.file]
+				: [];
+
+		const attachments: EmailAttachment[] = [];
+		for (const filePath of fileValues) {
+			const file = Bun.file(filePath);
+			if (!(await file.exists())) {
+				tui.fatal(`Attachment file not found: ${filePath}`);
+			}
+
+			const buffer = Buffer.from(await file.arrayBuffer());
+			attachments.push({
+				filename: basename(filePath),
+				contentType: file.type || 'application/octet-stream',
+				content: buffer.toString('base64'),
+			});
+		}
+
+		const email = await createEmailAdapter(ctx);
+		const outbound = await email.send({
+			to: [args.to],
+			from: opts.from,
+			subject: opts.subject,
+			text: opts.text,
+			html: opts.html,
+			attachments: attachments.length > 0 ? attachments : undefined,
+		});
+
+		if (!options.json) {
+			tui.success('Email queued for delivery');
+			tui.table(
+				[
+					{
+						ID: outbound.id,
+						From: outbound.from || opts.from,
+						To: outbound.to || args.to,
+						Subject: outbound.subject ?? opts.subject,
+						Text: truncate(outbound.text ?? opts.text),
+						Status: outbound.status ?? 'pending',
+						Attachments: attachments.length > 0 ? attachments.length.toString() : '-',
+					},
+				],
+				['ID', 'From', 'To', 'Subject', 'Text', 'Status', 'Attachments'],
+				{ layout: 'vertical', padStart: '  ' }
+			);
+		}
+
+		return outbound;
+	},
+});
+
+export default sendSubcommand;

package/src/cmd/cloud/email/stats.ts

@@ -0,0 +1,77 @@
+import { z } from 'zod';
+import { createCommand } from '../../../types';
+import * as tui from '../../../tui';
+import { getGlobalCatalystAPIClient } from '../../../config';
+import { getCommand } from '../../../command-prefix';
+import { getServiceStats, type ServiceStatsData } from '@agentuity/server';
+
+function formatNumber(n: number): string {
+	if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+	if (n >= 1_000) return `${(n / 1_000).toFixed(1)}K`;
+	return String(n);
+}
+
+function displayStats(data: ServiceStatsData): void {
+	const svc = data.services.email;
+	if (!svc) {
+		tui.info('No email data found.');
+		return;
+	}
+	tui.header('Email Statistics');
+	tui.newline();
+	console.log(
+		`  ${tui.muted('Addresses:')}       ${formatNumber(svc.addressCount)}`
+	);
+	console.log(
+		`  ${tui.muted('Inbound:')}         ${formatNumber(svc.inboundCount)}`
+	);
+	console.log(
+		`  ${tui.muted('Outbound:')}        ${formatNumber(svc.outboundCount)} (${svc.outboundSuccess} ok, ${svc.outboundFailed} failed)`
+	);
+}
+
+export const statsSubcommand = createCommand({
+	name: 'stats',
+	description: 'View email statistics',
+	tags: ['read-only', 'requires-auth'],
+	requires: { auth: true, org: true },
+	examples: [
+		{
+			command: getCommand('cloud email stats'),
+			description: 'View email statistics',
+		},
+	],
+	schema: {
+		options: z.object({
+			start: z.string().optional().describe('Start time (ISO 8601)'),
+			end: z.string().optional().describe('End time (ISO 8601)'),
+		}),
+	},
+	idempotent: true,
+
+	async handler(ctx) {
+		const { opts, options } = ctx;
+		const client = await getGlobalCatalystAPIClient(ctx.logger, ctx.auth, ctx.config?.name);
+		const orgId = ctx.orgId ?? ctx.options.orgId ?? ctx.config?.preferences?.orgId;
+
+		if (!orgId) {
+			ctx.logger.fatal('Organization ID is required. Use --org-id or set a preferred org.');
+			return;
+		}
+
+		const data = await getServiceStats(client, orgId, {
+			service: 'email',
+			start: opts.start,
+			end: opts.end,
+			orgIdHeader: orgId,
+		});
+
+		if (!options.json) {
+			displayStats(data);
+		}
+
+		return data;
+	},
+});
+
+export default statsSubcommand;

package/src/cmd/cloud/email/util.ts

@@ -0,0 +1,70 @@
+import { z } from 'zod';
+import { EmailStorageService, type Logger } from '@agentuity/core';
+import { createServerFetchAdapter } from '@agentuity/server';
+import type { AuthData, Config, GlobalOptions } from '../../../types';
+import { getCatalystUrl } from '../../../catalyst';
+import { defaultProfileName, getDefaultRegion } from '../../../config';
+import * as tui from '../../../tui';
+
+export type {
+	EmailAddress,
+	EmailDestination,
+	EmailInbound,
+	EmailOutbound,
+	EmailAttachment,
+	EmailSendParams,
+} from '@agentuity/core';
+
+export interface EmailContext {
+	logger: Logger;
+	auth: AuthData;
+	config: Config | null;
+	options: GlobalOptions;
+}
+
+export function resolveEmailOrgId(ctx: EmailContext): string {
+	const orgId =
+		ctx.options.orgId ??
+		(process.env.AGENTUITY_CLOUD_ORG_ID || ctx.config?.preferences?.orgId);
+
+	if (!orgId) {
+		tui.fatal('Organization ID is required. Use --org-id flag or set AGENTUITY_CLOUD_ORG_ID.');
+	}
+
+	return orgId;
+}
+
+export const EmailAddressSchema = z.object({
+	id: z.string(),
+	email: z.string(),
+	project_id: z.string().optional(),
+	provider: z.string().optional(),
+	config: z.record(z.string(), z.unknown()).optional(),
+	created_at: z.string(),
+	updated_at: z.string().optional(),
+});
+
+export function truncate(value: string | undefined, length = 200): string {
+	if (!value) {
+		return '-';
+	}
+	return value.length > length ? `${value.slice(0, length - 3)}...` : value;
+}
+
+export async function createEmailAdapter(ctx: EmailContext, region?: string) {
+	const orgId = resolveEmailOrgId(ctx);
+	const adapter = createServerFetchAdapter(
+		{
+			headers: {
+				Authorization: `Bearer ${ctx.auth.apiKey}`,
+				'x-agentuity-orgid': orgId,
+			},
+		},
+		ctx.logger
+	);
+
+	const resolvedRegion =
+		region ?? (await getDefaultRegion(ctx.config?.name ?? defaultProfileName, ctx.config));
+	const baseUrl = getCatalystUrl(resolvedRegion);
+	return new EmailStorageService(baseUrl, adapter);
+}

package/src/cmd/cloud/index.ts

@@ -10,12 +10,17 @@ import { scpSubcommand } from './scp';
 import { deploymentCommand } from './deployment';
 import keyvalueCommand from './keyvalue';
 import queueCommand from './queue';
+import webhookCommand from './webhook';
 import { agentCommand } from './agent';
 import envCommand from './env';
 import apikeyCommand from './apikey';
 import streamCommand from './stream';
 import vectorCommand from './vector';
+import { emailCommand } from './email';
+import taskCommand from './task';
 import sandboxCommand from './sandbox';
+import scheduleCommand from './schedule';
+import servicesCommand from './services';
 import { regionSubcommand } from './region';
 import { machineCommand } from './machine';
 import { evalCommand } from './eval';
@@ -35,10 +40,14 @@ export const command = createCommand({
 		apikeyCommand,
 		keyvalueCommand,
 		queueCommand,
+		webhookCommand,
+		taskCommand,
 		agentCommand,
 		streamCommand,
+		emailCommand,
 		vectorCommand,
 		sandboxCommand,
+		scheduleCommand,
 		envCommand,
 		evalCommand,
 		evalRunCommand,
@@ -46,6 +55,7 @@ export const command = createCommand({
 		dbCommand,
 		redisCommand,
 		storageCommand,
+		servicesCommand,
 		sessionCommand,
 		threadCommand,
 		sshSubcommand,

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

@@ -42,12 +42,12 @@ function displayMessage(message: Message): void {
 	tui.table([details], undefined, { layout: 'vertical' });
 
 	tui.newline();
-	tui.info('Payload');
+	tui.header('Payload');
 	tui.json(message.payload);
 
 	if (message.metadata && Object.keys(message.metadata).length > 0) {
 		tui.newline();
-		tui.info('Metadata');
+		tui.header('Metadata');
 		tui.json(message.metadata);
 	}
 }
@@ -119,7 +119,7 @@ export const getSubcommand = createCommand({
 				queue.next_offset !== undefined
 			) {
 				tui.newline();
-				tui.info('Stats');
+				tui.header('Stats');
 				tui.table(
 					[
 						{
@@ -135,7 +135,7 @@ export const getSubcommand = createCommand({
 
 			if (queue.default_visibility_timeout_seconds !== undefined) {
 				tui.newline();
-				tui.info('Settings');
+				tui.header('Settings');
 				const settings: Record<string, unknown> = {};
 				if (queue.default_ttl_seconds != null) {
 					settings['Default TTL'] = `${queue.default_ttl_seconds}s`;

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

@@ -55,15 +55,23 @@ export const receiveSubcommand = createCommand({
 				tui.info('No messages available');
 			} else {
 				tui.success(`Received message: ${message.id}`);
-				tui.info(`  Offset: ${message.offset}`);
-				tui.info(`  State: ${message.state}`);
-				tui.info(`  Delivery Attempts: ${message.delivery_attempts}`);
-				tui.info('');
-				tui.info('Payload:');
+				tui.table(
+					[
+						{
+							Offset: message.offset,
+							State: message.state,
+							'Delivery Attempts': message.delivery_attempts,
+						},
+					],
+					undefined,
+					{ layout: 'vertical' }
+				);
+				tui.newline();
+				tui.header('Payload');
 				tui.json(message.payload);
 				if (message.metadata) {
-					tui.info('');
-					tui.info('Metadata:');
+					tui.newline();
+					tui.header('Metadata');
 					tui.json(message.metadata);
 				}
 			}

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

@@ -45,7 +45,7 @@ function formatDuration(start: string, end: string): string {
 function displayOrgAnalytics(analytics: OrgAnalytics): void {
 	const { summary, queues, period } = analytics;
 
-	tui.info(`Organization Analytics (${formatDuration(period.start, period.end)})`);
+	tui.header(`Organization Analytics (${formatDuration(period.start, period.end)})`);
 	tui.newline();
 	console.log(tui.colorPrimary('Summary:'));
 	console.log(`  ${tui.muted('Total Queues:')}     ${summary.total_queues}`);
@@ -84,7 +84,7 @@ function displayQueueAnalytics(analytics: QueueAnalytics): void {
 	const { queue_name, queue_type, period, current, period_stats, latency, consumer_latency } =
 		analytics;
 
-	tui.info(`Queue: ${queue_name} (${queue_type})`);
+	tui.header(`Queue: ${queue_name} (${queue_type})`);
 	console.log(tui.colorWarning(`Period: ${formatDuration(period.start, period.end)}`));
 	tui.newline();
 
@@ -146,7 +146,7 @@ function displayQueueAnalytics(analytics: QueueAnalytics): void {
 
 	if (analytics.destinations && analytics.destinations.length > 0) {
 		tui.newline();
-		tui.info('Destinations:');
+		tui.header('Destinations');
 		const destData = analytics.destinations.map((d) => {
 			const total = d.success_count + d.failure_count;
 			const errorRate = total > 0 ? (d.failure_count / total) * 100 : 0;

package/src/cmd/cloud/region-lookup.ts

@@ -1,8 +1,9 @@
-import { StreamStorageService, type Logger } from '@agentuity/core';
+import { StreamStorageService, TaskStorageService, type Logger } from '@agentuity/core';
 import {
 	projectGet,
 	sandboxResolve,
 	deploymentGet,
+	getWebhook,
 	type APIClient,
 	createServerFetchAdapter,
 	getServiceUrls,
@@ -13,7 +14,7 @@ import type { AuthData, Config } from '../../types';
 import * as tui from '../../tui';
 import { ErrorCode } from '../../errors';
 
-export type IdentifierType = 'project' | 'deployment' | 'sandbox' | 'stream';
+export type IdentifierType = 'project' | 'deployment' | 'sandbox' | 'stream' | 'webhook' | 'task';
 
 /**
  * Determine the type of identifier based on its prefix
@@ -28,9 +29,15 @@ export function getIdentifierType(identifier: string): IdentifierType {
 	if (identifier.startsWith('sbx_')) {
 		return 'sandbox';
 	}
+	if (identifier.startsWith('task_')) {
+		return 'task';
+	}
 	if (identifier.startsWith('stream_')) {
 		return 'stream';
 	}
+	if (identifier.startsWith('wh_')) {
+		return 'webhook';
+	}
 	// Default to project for unknown prefixes
 	return 'project';
 }
@@ -82,6 +89,34 @@ export async function getIdentifierRegion(
 		}
 		const deployment = await deploymentGet(apiClient, identifier);
 		region = deployment.cloudRegion ?? null;
+	} else if (identifierType === 'task') {
+		// Tasks live in per-tenant DBs accessible from any regional Catalyst.
+		// Use default region to reach Catalyst, which can resolve the task for the org.
+		const taskDefaultRegion = await getDefaultRegion(profileName, config);
+		const taskBaseUrl = getServiceUrls(taskDefaultRegion).catalyst;
+		const resolvedTaskOrgId =
+			orgId ?? process.env.AGENTUITY_CLOUD_ORG_ID ?? config?.preferences?.orgId;
+		if (!resolvedTaskOrgId) {
+			tui.fatal(
+				`Organization ID required to resolve task '${identifier}'. Use --org-id or set AGENTUITY_CLOUD_ORG_ID.`,
+				ErrorCode.INVALID_ARGUMENT
+			);
+		}
+		const taskAdapter = createServerFetchAdapter(
+			{
+				headers: {
+					Authorization: `Bearer ${auth.apiKey}`,
+					'x-agentuity-orgid': resolvedTaskOrgId,
+				},
+			},
+			logger
+		);
+		const taskService = new TaskStorageService(taskBaseUrl, taskAdapter);
+		const taskResult = await taskService.get(identifier);
+		if (taskResult) {
+			region = taskDefaultRegion;
+			orgId = resolvedTaskOrgId;
+		}
 	} else if (identifierType === 'sandbox') {
 		// sandbox - use CLI API to resolve across all orgs the user has access to
 		if (!apiClient) {
@@ -96,6 +131,27 @@ export async function getIdentifierRegion(
 		if (sandbox.orgId) {
 			orgId = sandbox.orgId;
 		}
+	} else if (identifierType === 'webhook') {
+		// Webhook tenant DB is not regional — any global Catalyst can serve the request.
+		// We still look up the webhook to validate it exists and cache the orgId.
+		if (!apiClient) {
+			tui.fatal(
+				`API client required for webhook region lookup. This is an internal error.`,
+				ErrorCode.INVALID_ARGUMENT
+			);
+		}
+		const resolvedOrgId =
+			orgId ?? process.env.AGENTUITY_CLOUD_ORG_ID ?? config?.preferences?.orgId;
+		const webhook = await getWebhook(
+			apiClient,
+			identifier,
+			resolvedOrgId ? { orgId: resolvedOrgId } : undefined
+		);
+		if (webhook) {
+			orgId = resolvedOrgId;
+		}
+		// Use default region since webhooks are global
+		region = await getDefaultRegion(profileName, config);
 	} else {
 		// stream - use the streams service to look up stream info
 		// Any regional streams service can look up any stream and return its info