@agentuity/cli 0.0.58 → 0.0.59

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

@@ -0,0 +1,146 @@
+import { z } from 'zod';
+import { createCommand } from '../../../types';
+import * as tui from '../../../tui';
+import { createStorageAdapter } from './util';
+import { getCommand } from '../../../command-prefix';
+
+function formatBytes(bytes: number): string {
+	if (bytes === 0) return '0 B';
+	if (bytes < 1024) return `${bytes} B`;
+	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(2)} KB`;
+	if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
+	return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+}
+
+const StreamInfoSchema = z.object({
+	id: z.string().describe('Stream ID'),
+	name: z.string().describe('Stream name'),
+	metadata: z.record(z.string(), z.string()).describe('Stream metadata'),
+	url: z.string().describe('Public URL'),
+	sizeBytes: z.number().describe('Size in bytes'),
+});
+
+const ListStreamsResponseSchema = z.object({
+	streams: z.array(StreamInfoSchema).describe('List of streams'),
+	total: z.number().describe('Total count of matching streams'),
+});
+
+export const listSubcommand = createCommand({
+	name: 'list',
+	aliases: ['ls'],
+	description: 'List recent streams with optional filtering',
+	tags: ['read-only', 'slow', 'requires-auth'],
+	requires: { auth: true, project: true },
+	idempotent: true,
+	examples: [
+		`${getCommand('stream list')} - List all streams`,
+		`${getCommand('stream ls --size 50')} - List 50 most recent streams`,
+		`${getCommand('stream list --name agent-logs')} - Filter by name`,
+		`${getCommand('stream list --metadata type=export')} - Filter by metadata`,
+		`${getCommand('stream ls --json')} - Output as JSON`,
+	],
+	schema: {
+		options: z.object({
+			size: z.number().optional().describe('maximum number of streams to return (default: 100)'),
+			offset: z.number().optional().describe('number of streams to skip for pagination'),
+			name: z.string().optional().describe('filter by stream name'),
+			metadata: z
+				.string()
+				.optional()
+				.describe('filter by metadata (format: key=value or key1=value1,key2=value2)'),
+		}),
+		response: ListStreamsResponseSchema,
+	},
+
+	async handler(ctx) {
+		const { opts, options } = ctx;
+		const storage = await createStorageAdapter(ctx);
+
+		// Parse metadata filter if provided
+		let metadataFilter: Record<string, string> | undefined;
+		if (opts.metadata) {
+			const validPairs: Record<string, string> = {};
+			const malformed: string[] = [];
+			const pairs = opts.metadata.split(',');
+
+			for (const pair of pairs) {
+				const trimmedPair = pair.trim();
+				if (!trimmedPair) continue;
+
+				const firstEqualIdx = trimmedPair.indexOf('=');
+				if (firstEqualIdx === -1) {
+					malformed.push(trimmedPair);
+					continue;
+				}
+
+				const key = trimmedPair.substring(0, firstEqualIdx).trim();
+				const value = trimmedPair.substring(firstEqualIdx + 1).trim();
+
+				if (!key || !value) {
+					malformed.push(trimmedPair);
+					continue;
+				}
+
+				validPairs[key] = value;
+			}
+
+			if (malformed.length > 0) {
+				ctx.logger.warn(`Skipping malformed metadata pairs: ${malformed.join(', ')}`);
+			}
+
+			if (Object.keys(validPairs).length > 0) {
+				metadataFilter = validPairs;
+			}
+		}
+
+		const result = await storage.list({
+			limit: opts.size,
+			offset: opts.offset,
+			name: opts.name,
+			metadata: metadataFilter,
+		});
+
+		if (options.json) {
+			console.log(JSON.stringify(result, null, 2));
+			return {
+				streams: result.streams,
+				total: result.total,
+			};
+		}
+
+		if (result.streams.length === 0) {
+			tui.info('No streams found');
+		} else {
+			const tableData = result.streams.map((stream) => {
+				const sizeBytes = stream.sizeBytes ?? 0;
+				const metadataStr =
+					Object.keys(stream.metadata).length > 0 ? JSON.stringify(stream.metadata) : '-';
+				return {
+					Name: stream.name,
+					ID: stream.id,
+					Size: formatBytes(sizeBytes),
+					Metadata:
+						metadataStr.length > 40 ? metadataStr.substring(0, 37) + '...' : metadataStr,
+					URL: tui.link(stream.url),
+				};
+			});
+
+			tui.table(tableData, [
+				{ name: 'Name', alignment: 'left' },
+				{ name: 'ID', alignment: 'left' },
+				{ name: 'Size', alignment: 'right' },
+				{ name: 'Metadata', alignment: 'left' },
+				{ name: 'URL', alignment: 'left' },
+			]);
+
+			tui.info(`Total: ${result.total} stream(s)`);
+		}
+
+		return {
+			streams: result.streams,
+			total: result.total,
+		};
+	},
+});
+
+export default listSubcommand;

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

@@ -0,0 +1,32 @@
+import { StreamStorageService, Logger } from '@agentuity/core';
+import { createServerFetchAdapter } from '@agentuity/server';
+import { loadProjectSDKKey } from '../../../config';
+import { ErrorCode } from '../../../errors';
+import type { Config } from '../../../types';
+import * as tui from '../../../tui';
+
+export async function createStorageAdapter(ctx: {
+	logger: Logger;
+	projectDir: string;
+	config: Config | null;
+}) {
+	const sdkKey = await loadProjectSDKKey(ctx.projectDir);
+	if (!sdkKey) {
+		tui.fatal(
+			`Couldn't find the AGENTUITY_SDK_KEY in ${ctx.projectDir} .env file`,
+			ErrorCode.CONFIG_NOT_FOUND
+		);
+	}
+
+	const adapter = createServerFetchAdapter(
+		{
+			headers: {
+				Authorization: `Bearer ${sdkKey}`,
+			},
+		},
+		ctx.logger
+	);
+
+	const baseUrl = ctx.config?.overrides?.stream_url ?? 'https://stream.agentuity.cloud';
+	return new StreamStorageService(baseUrl, adapter);
+}

package/src/cmd/cloud/vector/delete.ts

@@ -0,0 +1,105 @@
+import { z } from 'zod';
+import { createCommand } from '../../../types';
+import { ErrorCode } from '../../../errors';
+import * as tui from '../../../tui';
+import { createStorageAdapter } from './util';
+import { getCommand } from '../../../command-prefix';
+
+const VectorDeleteResponseSchema = z.object({
+	success: z.boolean().describe('Whether the operation succeeded'),
+	namespace: z.string().describe('Namespace name'),
+	keys: z.array(z.string()).describe('Keys that were deleted'),
+	deleted: z.number().describe('Number of vectors deleted'),
+	durationMs: z.number().describe('Operation duration in milliseconds'),
+	message: z.string().optional().describe('Confirmation message'),
+});
+
+export const deleteSubcommand = createCommand({
+	name: 'delete',
+	aliases: ['del', 'rm'],
+	description: 'Delete one or more vectors by key',
+	tags: ['destructive', 'deletes-resource', 'slow', 'requires-auth'],
+	requires: { auth: true, project: true },
+	idempotent: true,
+	examples: [
+		`${getCommand('vector delete products chair-001')} - Delete a single vector (interactive)`,
+		`${getCommand('vector rm knowledge-base doc-123 doc-456 --confirm')} - Delete multiple vectors without confirmation`,
+		`${getCommand('vector del embeddings old-profile-1 old-profile-2 --confirm')} - Bulk delete without confirmation`,
+	],
+	schema: {
+		args: z.object({
+			namespace: z.string().min(1).describe('the vector storage namespace'),
+			keys: z.array(z.string().min(1)).min(1).describe('one or more keys to delete'),
+		}),
+		options: z.object({
+			confirm: z
+				.boolean()
+				.optional()
+				.default(false)
+				.describe('if true will not prompt for confirmation'),
+		}),
+		response: VectorDeleteResponseSchema,
+	},
+
+	async handler(ctx) {
+		const { args, options, opts } = ctx;
+
+		if (!opts.confirm) {
+			if (!process.stdin.isTTY) {
+				tui.fatal(
+					'No TTY and --confirm is not set. Refusing to delete',
+					ErrorCode.VALIDATION_FAILED
+				);
+			}
+			const keyList = args.keys.length > 3 ? `${args.keys.slice(0, 3).join(', ')}...` : args.keys.join(', ');
+			tui.warning(`This will delete ${args.keys.length} vector(s) from ${tui.bold(args.namespace)}: ${keyList}`);
+			const confirm = await new Promise<boolean>((resolve) => {
+				process.stdout.write('Are you sure? (yes/no): ');
+				process.stdin.once('data', (data) => {
+					const answer = data.toString().trim().toLowerCase();
+					resolve(answer === 'yes' || answer === 'y');
+				});
+			});
+
+			if (!confirm) {
+				tui.info('Cancelled');
+				return {
+					success: false,
+					namespace: args.namespace,
+					keys: args.keys,
+					deleted: 0,
+					durationMs: 0,
+					message: 'Cancelled',
+				};
+			}
+		}
+
+		const storage = await createStorageAdapter(ctx);
+		const started = Date.now();
+
+		const deleted = await storage.delete(args.namespace, ...args.keys);
+		const durationMs = Date.now() - started;
+
+		if (!options.json) {
+			if (deleted > 0) {
+				tui.success(
+					`Deleted ${deleted} vector(s) from ${tui.bold(args.namespace)} (${durationMs}ms)`
+				);
+			} else {
+				tui.warning(
+					`No vectors were deleted from ${tui.bold(args.namespace)} (keys may not exist)`
+				);
+			}
+		}
+
+		return {
+			success: true,
+			namespace: args.namespace,
+			keys: args.keys,
+			deleted,
+			durationMs,
+		};
+	},
+});
+
+export default deleteSubcommand;

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

@@ -0,0 +1,94 @@
+import { z } from 'zod';
+import { createCommand } from '../../../types';
+import * as tui from '../../../tui';
+import { createStorageAdapter } from './util';
+import { getCommand } from '../../../command-prefix';
+
+const VectorGetResponseSchema = z.object({
+	exists: z.boolean().describe('Whether the vector exists'),
+	key: z.string().optional().describe('Vector key'),
+	id: z.string().optional().describe('Vector ID'),
+	metadata: z.record(z.string(), z.unknown()).optional().describe('Vector metadata'),
+	document: z.string().optional().describe('Original document text'),
+	similarity: z.number().optional().describe('Similarity score'),
+});
+
+export const getSubcommand = createCommand({
+	name: 'get',
+	description: 'Get a specific vector entry by key',
+	tags: ['read-only', 'fast', 'requires-auth'],
+	requires: { auth: true, project: true },
+	idempotent: true,
+	examples: [
+		`${getCommand('vector get products chair-001')} - Get a specific product vector`,
+		`${getCommand('vector get knowledge-base doc-123')} - Get a document from knowledge base`,
+		`${getCommand('vector get embeddings user-profile-456')} - Get user profile embedding`,
+	],
+	schema: {
+		args: z.object({
+			namespace: z.string().min(1).describe('the vector storage namespace'),
+			key: z.string().min(1).describe('the key of the vector to retrieve'),
+		}),
+		response: VectorGetResponseSchema,
+	},
+
+	async handler(ctx) {
+		const { args, options } = ctx;
+		const storage = await createStorageAdapter(ctx);
+		const started = Date.now();
+
+		const result = await storage.get(args.namespace, args.key);
+		const durationMs = Date.now() - started;
+
+		if (!options.json) {
+			if (result.exists) {
+				tui.success(
+					`Found vector "${tui.bold(args.key)}" in ${tui.bold(args.namespace)} (${durationMs}ms)`
+				);
+
+				const data = result.data;
+				tui.info(`  ID: ${data.id}`);
+				tui.info(`  Key: ${data.key}`);
+
+				if (data.similarity !== undefined) {
+					tui.info(`  Similarity: ${(data.similarity * 100).toFixed(1)}%`);
+				}
+
+				if (data.document) {
+					const docPreview =
+						data.document.length > 200
+							? data.document.substring(0, 197) + '...'
+							: data.document;
+					tui.info(`  Document: ${docPreview}`);
+				}
+
+				if (data.metadata && Object.keys(data.metadata).length > 0) {
+					tui.info(`  Metadata: ${JSON.stringify(data.metadata, null, 2)}`);
+				}
+
+				if (data.embeddings) {
+					tui.info(`  Embeddings: [${data.embeddings.length} dimensions]`);
+				}
+			} else {
+				tui.warning(`Vector "${tui.bold(args.key)}" not found in ${tui.bold(args.namespace)}`);
+			}
+		}
+
+		if (result.exists) {
+			return {
+				exists: true,
+				key: result.data.key,
+				id: result.data.id,
+				metadata: result.data.metadata,
+				document: result.data.document,
+				similarity: result.data.similarity,
+			};
+		}
+
+		return {
+			exists: false,
+		};
+	},
+});
+
+export default getSubcommand;

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

@@ -0,0 +1,15 @@
+import { createCommand } from '../../../types';
+import { deleteSubcommand } from './delete';
+import { getSubcommand } from './get';
+import { searchSubcommand } from './search';
+
+export const vectorCommand = createCommand({
+	name: 'vector',
+	aliases: ['vec'],
+	description: 'Manage vector storage for your projects',
+	tags: ['requires-auth', 'destructive', 'deletes-resource', 'slow'],
+	subcommands: [searchSubcommand, getSubcommand, deleteSubcommand],
+	requires: { auth: true, project: true },
+});
+
+export default vectorCommand;

package/src/cmd/cloud/vector/search.ts

@@ -0,0 +1,156 @@
+import { z } from 'zod';
+import { createCommand } from '../../../types';
+import * as tui from '../../../tui';
+import { createStorageAdapter } from './util';
+import { getCommand } from '../../../command-prefix';
+
+const VectorSearchResultSchema = z.object({
+	id: z.string().describe('Vector ID'),
+	key: z.string().describe('Vector key'),
+	similarity: z.number().describe('Similarity score (0-1)'),
+	metadata: z.record(z.string(), z.unknown()).optional().describe('Vector metadata'),
+});
+
+const VectorSearchResponseSchema = z.object({
+	namespace: z.string().describe('Namespace name'),
+	query: z.string().describe('Search query used'),
+	results: z.array(VectorSearchResultSchema).describe('Search results'),
+	count: z.number().describe('Number of results found'),
+});
+
+export const searchSubcommand = createCommand({
+	name: 'search',
+	aliases: ['list', 'ls'],
+	description: 'Search for vectors using semantic similarity',
+	tags: ['read-only', 'slow', 'requires-auth'],
+	requires: { auth: true, project: true },
+	idempotent: true,
+	examples: [
+		`${getCommand('vector search products "comfortable office chair"')} - Search for similar products`,
+		`${getCommand('vector list knowledge-base "machine learning"')} - Search knowledge base`,
+		`${getCommand('vector search docs "API documentation" --limit 5')} - Limit results`,
+		`${getCommand('vector search products "ergonomic" --similarity 0.8')} - Set minimum similarity`,
+		`${getCommand('vector ls embeddings "neural networks" --metadata category=ai')} - Filter by metadata`,
+	],
+	schema: {
+		args: z.object({
+			namespace: z.string().min(1).describe('the vector storage namespace'),
+			query: z.string().min(1).describe('the search query text'),
+		}),
+		options: z.object({
+			limit: z.number().optional().describe('maximum number of results to return (default: 10)'),
+			similarity: z
+				.number()
+				.min(0)
+				.max(1)
+				.optional()
+				.describe('minimum similarity threshold (0.0-1.0)'),
+			metadata: z
+				.string()
+				.optional()
+				.describe('filter by metadata (format: key=value or key1=value1,key2=value2)'),
+		}),
+		response: VectorSearchResponseSchema,
+	},
+
+	async handler(ctx) {
+		const { args, opts, options } = ctx;
+		const storage = await createStorageAdapter(ctx);
+		const started = Date.now();
+
+		// Parse metadata filter if provided
+		let metadataFilter: Record<string, unknown> | undefined;
+		if (opts.metadata) {
+			const validPairs: Record<string, unknown> = {};
+			const malformed: string[] = [];
+			const pairs = opts.metadata.split(',');
+
+			for (const pair of pairs) {
+				const trimmedPair = pair.trim();
+				if (!trimmedPair) continue;
+
+				const firstEqualIdx = trimmedPair.indexOf('=');
+				if (firstEqualIdx === -1) {
+					malformed.push(trimmedPair);
+					continue;
+				}
+
+				const key = trimmedPair.substring(0, firstEqualIdx).trim();
+				const value = trimmedPair.substring(firstEqualIdx + 1).trim();
+
+				if (!key || !value) {
+					malformed.push(trimmedPair);
+					continue;
+				}
+
+				// Try to parse as JSON for complex values, otherwise use as string
+				try {
+					validPairs[key] = JSON.parse(value);
+				} catch {
+					validPairs[key] = value;
+				}
+			}
+
+			if (malformed.length > 0) {
+				ctx.logger.warn(`Skipping malformed metadata pairs: ${malformed.join(', ')}`);
+			}
+
+			if (Object.keys(validPairs).length > 0) {
+				metadataFilter = validPairs;
+			}
+		}
+
+		const results = await storage.search(args.namespace, {
+			query: args.query,
+			limit: opts.limit,
+			similarity: opts.similarity,
+			metadata: metadataFilter,
+		});
+
+		const durationMs = Date.now() - started;
+
+		if (!options.json) {
+			if (results.length === 0) {
+				tui.info(
+					`No vectors found matching "${tui.bold(args.query)}" in ${tui.bold(args.namespace)}`
+				);
+			} else {
+				tui.info(
+					`Found ${results.length} result(s) in ${tui.bold(args.namespace)} (${durationMs}ms):`
+				);
+
+				const tableData = results.map((result) => {
+					const metadataStr = result.metadata ? JSON.stringify(result.metadata) : '-';
+					return {
+						Key: result.key,
+						ID: result.id,
+						Similarity: `${(result.similarity * 100).toFixed(1)}%`,
+						Metadata:
+							metadataStr.length > 50 ? metadataStr.substring(0, 47) + '...' : metadataStr,
+					};
+				});
+
+				tui.table(tableData, [
+					{ name: 'Key', alignment: 'left' },
+					{ name: 'ID', alignment: 'left' },
+					{ name: 'Similarity', alignment: 'right' },
+					{ name: 'Metadata', alignment: 'left' },
+				]);
+			}
+		}
+
+		return {
+			namespace: args.namespace,
+			query: args.query,
+			results: results.map((r) => ({
+				id: r.id,
+				key: r.key,
+				similarity: r.similarity,
+				metadata: r.metadata,
+			})),
+			count: results.length,
+		};
+	},
+});
+
+export default searchSubcommand;

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

@@ -0,0 +1,28 @@
+import { Logger, VectorStorageService } from '@agentuity/core';
+import { createServerFetchAdapter } from '@agentuity/server';
+import { loadProjectSDKKey } from '../../../config';
+import type { Config } from '../../../types';
+import * as tui from '../../../tui';
+
+export async function createStorageAdapter(ctx: {
+	logger: Logger;
+	projectDir: string;
+	config: Config | null;
+}) {
+	const sdkKey = await loadProjectSDKKey(ctx.projectDir);
+	if (!sdkKey) {
+		tui.fatal(`Couldn't find the AGENTUITY_SDK_KEY in ${ctx.projectDir} .env file`);
+	}
+
+	const adapter = createServerFetchAdapter(
+		{
+			headers: {
+				Authorization: `Bearer ${sdkKey}`,
+			},
+		},
+		ctx.logger
+	);
+
+	const baseUrl = ctx.config?.overrides?.catalyst_url ?? 'https://catalyst.agentuity.cloud';
+	return new VectorStorageService(baseUrl, adapter);
+}

package/src/cmd/dev/agents.ts

@@ -8,7 +8,7 @@ const AgentSchema = z.object({
 	id: z.string(),
 	name: z.string(),
 	description: z.string().nullable(),
-	identifier: z.string(),
+	identifier: z.string().nullable(), // nullable for legacy records
 	version: z.string().nullable(),
 	deploymentId: z.string().nullable(),
 	devmode: z.boolean(),
@@ -75,7 +75,8 @@ export const agentsSubcommand = createSubcommand({
 			tui.fatal(`Failed to fetch agents: ${response.message ?? 'Unknown error'}`);
 		}
 
-		const agents = response.data;
+		// Filter out legacy agents without identifiers
+		const agents = response.data.filter((agent) => agent.identifier !== null);
 
 		if (format === 'json' && !options.json) {
 			console.log(JSON.stringify(agents, null, 2));
@@ -91,7 +92,7 @@ export const agentsSubcommand = createSubcommand({
 					agents.map((agent) => ({
 						name: agent.name,
 						id: verbose ? agent.id : abbreviate(agent.id, 20),
-						identifier: verbose ? agent.identifier : abbreviate(agent.identifier, 20),
+						identifier: verbose ? agent.identifier! : abbreviate(agent.identifier!, 20),
 						deployment: abbreviate(agent.deploymentId, 20),
 						version: verbose
 							? (agent.version ?? 'N/A')

package/src/cmd/dev/index.ts

@@ -110,7 +110,7 @@ export const command = createCommand({
 		);
 		const deploymentId = getDevmodeDeploymentId(project?.projectId ?? '', devmode?.id ?? '');
 
-		if (devmode) {
+		if (devmode && opts.public) {
 			const configDir = getDefaultConfigDir();
 			const gravityDir = join(configDir, 'gravity');
 			let mustCheck = true;
@@ -242,7 +242,7 @@ export const command = createCommand({
 		if (!sdkKey) {
 			tui.warning(`Couldn't find the AGENTUITY_SDK_KEY in ${rootDir} .env file`);
 		}
-		const gravityBinExists = gravityBin ? await Bun.file(gravityBin).exists() : undefined;
+		const gravityBinExists = gravityBin ? await Bun.file(gravityBin).exists() : true;
 		if (!gravityBinExists) {
 			logger.error(`Gravity binary not found at ${gravityBin}, skipping gravity client startup`);
 		}
@@ -252,7 +252,7 @@ export const command = createCommand({
 				gravityClient.kill('SIGINT');
 				gravityClient.kill();
 			}
-			if (!devmode) {
+			if (!devmode || !opts.public) {
 				return;
 			}
 			try {