@agentuity/cli 1.0.36 → 1.0.38

package/src/cmd/cloud/task/user.ts

@@ -0,0 +1,202 @@
+import { z } from 'zod';
+import { createCommand } from '../../../types';
+import * as tui from '../../../tui';
+import { createStorageAdapter } from './util';
+import { getCommand } from '../../../command-prefix';
+
+// ── List ────────────────────────────────────────────────────────────────
+
+const listUsersSubcommand = createCommand({
+	name: 'list',
+	aliases: ['ls'],
+	description: 'List all task users',
+	tags: ['read-only', 'slow', 'requires-auth'],
+	requires: { auth: true },
+	idempotent: true,
+	examples: [
+		{
+			command: getCommand('cloud task user list'),
+			description: 'List all users',
+		},
+	],
+	schema: {
+		response: z.object({
+			success: z.boolean(),
+			users: z.array(
+				z.object({
+					id: z.string(),
+					name: z.string(),
+					type: z.string().optional(),
+				})
+			),
+			total: z.number(),
+			durationMs: z.number(),
+		}),
+	},
+
+	async handler(ctx) {
+		const { options } = ctx;
+		const started = Date.now();
+		const storage = await createStorageAdapter(ctx);
+		const result = await storage.listUsers();
+		const durationMs = Date.now() - started;
+
+		if (!options.json) {
+			if (result.users.length === 0) {
+				tui.info('No users found.');
+			} else {
+				tui.table(
+					result.users.map((u) => ({
+						id: u.id,
+						name: u.name,
+						type: (u as { type?: string }).type ?? 'human',
+					})),
+					['id', 'name', 'type']
+				);
+				tui.info(`${result.users.length} user(s) (${durationMs.toFixed(1)}ms)`);
+			}
+		}
+
+		return { success: true, users: result.users, total: result.users.length, durationMs };
+	},
+});
+
+// ── Create ──────────────────────────────────────────────────────────────
+
+const createUserSubcommand = createCommand({
+	name: 'create',
+	description: 'Create a new task user',
+	tags: ['mutating', 'slow', 'requires-auth'],
+	requires: { auth: true },
+	examples: [
+		{
+			command: getCommand('cloud task user create "Jane Doe"'),
+			description: 'Create a human user',
+		},
+		{
+			command: getCommand('cloud task user create "My Agent" --type agent'),
+			description: 'Create an agent user',
+		},
+	],
+	schema: {
+		args: z.object({
+			name: z.string().min(1).describe('the user display name'),
+		}),
+		options: z.object({
+			type: z.enum(['human', 'agent']).optional().describe('user type (human or agent)'),
+		}),
+		response: z.object({
+			success: z.boolean(),
+			user: z.object({
+				id: z.string(),
+				name: z.string(),
+				type: z.string().optional(),
+			}),
+			durationMs: z.number(),
+		}),
+	},
+
+	async handler(ctx) {
+		const { args, opts, options } = ctx;
+		const started = Date.now();
+		const storage = await createStorageAdapter(ctx);
+		const user = await storage.createUser({ name: args.name, type: opts.type });
+		const durationMs = Date.now() - started;
+
+		if (!options.json) {
+			tui.success(`Created user: ${user.name} (${user.id})`);
+		}
+
+		return { success: true, user, durationMs };
+	},
+});
+
+// ── Get ─────────────────────────────────────────────────────────────────
+
+const getUserSubcommand = createCommand({
+	name: 'get',
+	description: 'Get a task user by ID',
+	tags: ['read-only', 'slow', 'requires-auth'],
+	requires: { auth: true },
+	idempotent: true,
+	examples: [
+		{
+			command: getCommand('cloud task user get usr_abc123'),
+			description: 'Get user details',
+		},
+	],
+	schema: {
+		args: z.object({
+			id: z.string().min(1).describe('the user ID'),
+		}),
+		response: z.object({
+			success: z.boolean(),
+			user: z.object({
+				id: z.string(),
+				name: z.string(),
+				type: z.string().optional(),
+			}),
+			durationMs: z.number(),
+		}),
+	},
+
+	async handler(ctx) {
+		const { args, options } = ctx;
+		const started = Date.now();
+		const storage = await createStorageAdapter(ctx);
+		try {
+			const user = await storage.getUser(args.id);
+			const durationMs = Date.now() - started;
+
+			if (!options.json) {
+				tui.table(
+					[
+						{
+							id: user.id,
+							name: user.name,
+							type: (user as { type?: string }).type ?? 'human',
+						},
+					],
+					['id', 'name', 'type'],
+					{ layout: 'vertical' }
+				);
+			}
+
+			return { success: true, user, durationMs };
+		} catch (_err) {
+			const durationMs = Date.now() - started;
+			if (!options.json) {
+				tui.error(`User not found: ${args.id}`);
+			}
+			return {
+				success: false,
+				user: { id: args.id, name: '', type: 'human' as const },
+				durationMs,
+			};
+		}
+	},
+});
+
+// ── Parent command ──────────────────────────────────────────────────────
+
+export const userSubcommand = createCommand({
+	name: 'user',
+	description: 'Manage task users',
+	tags: ['requires-auth'],
+	requires: { auth: true },
+	examples: [
+		{
+			command: getCommand('cloud task user list'),
+			description: 'List all users',
+		},
+		{
+			command: getCommand('cloud task user create "Jane Doe"'),
+			description: 'Create a new user',
+		},
+		{
+			command: getCommand('cloud task user get usr_abc123'),
+			description: 'Get user details',
+		},
+	],
+	subcommands: [listUsersSubcommand, createUserSubcommand, getUserSubcommand],
+});

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

@@ -36,6 +36,24 @@ export async function createStorageAdapter(ctx: TaskContext) {
 	return new TaskStorageService(baseUrl, adapter);
 }
 
+export async function createStorageAdapterOptionalOrg(ctx: TaskContext) {
+	const orgId =
+		ctx.options.orgId ?? (process.env.AGENTUITY_CLOUD_ORG_ID || ctx.config?.preferences?.orgId);
+
+	const headers: Record<string, string> = {
+		Authorization: `Bearer ${ctx.auth.apiKey}`,
+	};
+	if (orgId) {
+		headers['x-agentuity-orgid'] = orgId;
+	}
+
+	const adapter = createServerFetchAdapter({ headers }, ctx.logger);
+
+	const region = await getDefaultRegion(ctx.config?.name ?? defaultProfileName, ctx.config);
+	const baseUrl = getCatalystUrl(region, ctx.config?.overrides);
+	return new TaskStorageService(baseUrl, adapter);
+}
+
 export async function cacheTaskId(
 	ctx: {
 		config: Config | null;

package/src/cmd/coder/hub-url.ts

@@ -0,0 +1,105 @@
+/**
+ * Hub URL resolution for Coder CLI commands.
+ *
+ * Resolution priority:
+ *   1. --hub-url flag (explicit per-command override)
+ *   2. AGENTUITY_CODER_HUB_URL env var
+ *   3. AGENTUITY_DEVMODE_URL env var (dev tunnel URL)
+ */
+
+import { getVersion } from '../../version';
+
+/**
+ * Resolve the Hub HTTP base URL for REST API calls.
+ * Converts ws:// URLs to http:// automatically.
+ *
+ * @param flagUrl  Optional --hub-url flag value
+ * @returns HTTP base URL (e.g. "http://localhost:3500") or null if Hub is unreachable
+ */
+export async function resolveHubUrl(flagUrl?: string): Promise<string | null> {
+	// 1. Explicit flag
+	if (flagUrl) return normalizeToHttp(flagUrl);
+
+	// 2. Env var (explicit)
+	const envUrl = process.env.AGENTUITY_CODER_HUB_URL;
+	if (envUrl) return normalizeToHttp(envUrl);
+
+	// 3. Dev mode URL (tunnel)
+	const devUrl = process.env.AGENTUITY_DEVMODE_URL;
+	if (devUrl) return normalizeToHttp(devUrl);
+
+	return null;
+}
+
+/**
+ * Resolve the Hub WebSocket URL for Pi extension connections.
+ * Converts http:// URLs to ws:// automatically and ensures /api/ws path.
+ *
+ * @param flagUrl  Optional --hub-url flag value
+ * @returns WebSocket URL (e.g. "ws://127.0.0.1:3500/api/ws") or null
+ */
+export async function resolveHubWsUrl(flagUrl?: string): Promise<string | null> {
+	const httpUrl = await resolveHubUrl(flagUrl);
+	if (!httpUrl) return null;
+	return normalizeToWs(httpUrl);
+}
+
+/**
+ * Convert any URL form to an HTTP base URL (strip paths, convert ws->http).
+ */
+function normalizeToHttp(url: string): string {
+	let normalized = url.trim().replace(/\/+$/, '');
+
+	// ws:// -> http://
+	if (normalized.startsWith('ws://')) normalized = 'http://' + normalized.slice(5);
+	else if (normalized.startsWith('wss://')) normalized = 'https://' + normalized.slice(6);
+
+	// Strip /api/ws or /api/hub/* paths to get base URL
+	normalized = normalized.replace(/\/api\/ws\b.*$/, '');
+	normalized = normalized.replace(/\/api\/hub\b.*$/, '');
+
+	return normalized.replace(/\/+$/, '');
+}
+
+/**
+ * Convert an HTTP base URL to a WebSocket URL with /api/ws path.
+ */
+function normalizeToWs(httpUrl: string): string {
+	let wsUrl = httpUrl;
+	if (wsUrl.startsWith('http://')) wsUrl = 'ws://' + wsUrl.slice(7);
+	else if (wsUrl.startsWith('https://')) wsUrl = 'wss://' + wsUrl.slice(8);
+
+	try {
+		const parsed = new URL(wsUrl);
+		if (parsed.pathname !== '/api/ws') {
+			parsed.pathname = '/api/ws';
+			wsUrl = parsed.toString().replace(/\/$/, '');
+		}
+	} catch {
+		if (!wsUrl.endsWith('/api/ws')) {
+			wsUrl = wsUrl.replace(/\/?$/, '/api/ws');
+		}
+	}
+
+	return wsUrl;
+}
+
+/**
+ * Resolve the API key for Hub authentication.
+ * TODO: Remove/Change when we get Agentuity service level auth enabled, this is just temporary
+ */
+export function resolveApiKey(): string | null {
+	return process.env.AGENTUITY_CODER_API_KEY || null;
+}
+
+/**
+ * Build headers object with API key if available.
+ * TODO: Remove/Change when we get Agentuity service level auth enabled, this is just temporary
+ */
+export function hubFetchHeaders(extra?: Record<string, string>): Record<string, string> {
+	const headers: Record<string, string> = { ...extra };
+	headers['User-Agent'] = `Agentuity Coder/${getVersion()}`;
+	const apiKey = resolveApiKey();
+	if (apiKey) headers['x-agentuity-auth-api-key'] = apiKey;
+	return headers;
+}

package/src/cmd/coder/index.ts

@@ -0,0 +1,27 @@
+import { createCommand } from '../../types';
+import { listSubcommand } from './list';
+import { inspectSubcommand } from './inspect';
+import { startSubcommand } from './start';
+import { getCommand } from '../../command-prefix';
+
+export const command = createCommand({
+	name: 'coder',
+	description: 'Coder Hub session management commands',
+	tags: ['requires-auth'],
+	examples: [
+		{
+			command: getCommand('coder start'),
+			description: 'Start a Pi session connected to the Coder Hub',
+		},
+		{
+			command: getCommand('coder ls'),
+			description: 'List all active Coder Hub sessions',
+		},
+		{
+			command: getCommand('coder inspect <session-id>'),
+			description: 'Show detailed session information',
+		},
+	],
+	subcommands: [startSubcommand, listSubcommand, inspectSubcommand],
+	optional: { auth: true },
+});

package/src/cmd/coder/inspect.ts

@@ -0,0 +1,200 @@
+import { z } from 'zod';
+import { createSubcommand } from '../../types';
+import * as tui from '../../tui';
+import { getCommand } from '../../command-prefix';
+import { ErrorCode } from '../../errors';
+import { resolveHubUrl, hubFetchHeaders } from './hub-url';
+
+function formatRelativeTime(isoDate: string): string {
+	const diffMs = Date.now() - new Date(isoDate).getTime();
+	const seconds = Math.floor(diffMs / 1000);
+	if (seconds < 60) return `${seconds}s ago`;
+	const minutes = Math.floor(seconds / 60);
+	if (minutes < 60) return `${minutes}m ago`;
+	const hours = Math.floor(minutes / 60);
+	if (hours < 24) return `${hours}h ago`;
+	const days = Math.floor(hours / 24);
+	return `${days}d ago`;
+}
+
+function formatDuration(ms: number): string {
+	const seconds = Math.floor(ms / 1000);
+	if (seconds < 60) return `${seconds}s`;
+	const minutes = Math.floor(seconds / 60);
+	const remainSec = seconds % 60;
+	if (minutes < 60) return `${minutes}m ${remainSec}s`;
+	const hours = Math.floor(minutes / 60);
+	const remainMin = minutes % 60;
+	return `${hours}h ${remainMin}m`;
+}
+
+export const inspectSubcommand = createSubcommand({
+	name: 'inspect',
+	description: 'Show detailed information about a Coder Hub session',
+	tags: ['read-only', 'fast', 'requires-auth'],
+	examples: [
+		{
+			command: getCommand('coder inspect codesess_abc123'),
+			description: 'Inspect a session by ID',
+		},
+		{
+			command: getCommand('coder inspect codesess_abc123 --json'),
+			description: 'Get session details as JSON',
+		},
+	],
+	idempotent: true,
+	schema: {
+		args: z.object({
+			session_id: z.string().describe('Coder session ID to inspect'),
+		}),
+		options: z.object({
+			hubUrl: z.string().optional().describe('Hub URL override'),
+		}),
+	},
+	async handler(ctx) {
+		const { args, options, opts } = ctx;
+		const sessionId = args.session_id;
+		const hubUrl = await resolveHubUrl(opts?.hubUrl);
+
+		if (!hubUrl) {
+			tui.fatal(
+				'Could not find a running Coder Hub.\n\nEither:\n  - Start the Hub with: bun run dev\n  - Set AGENTUITY_CODER_HUB_URL environment variable\n  - Pass --hub-url flag',
+				ErrorCode.NETWORK_ERROR
+			);
+			return;
+		}
+
+		let data: {
+			sessionId: string;
+			label: string;
+			status: string;
+			createdAt: string;
+			mode: string;
+			context: {
+				branch?: string;
+				workingDirectory?: string;
+			};
+			participants: Array<{
+				id: string;
+				role: string;
+				transport: string;
+				connectedAt: string;
+				idle: boolean;
+			}>;
+			tasks: Array<{
+				taskId: string;
+				agent: string;
+				status: string;
+				prompt: string;
+				duration?: number;
+				startedAt: string;
+				completedAt?: string;
+			}>;
+			agentActivity: Record<
+				string,
+				{
+					name: string;
+					status: string;
+					currentTool?: string;
+					toolCallCount: number;
+					lastActivity: number;
+				}
+			>;
+		};
+
+		try {
+			const resp = await fetch(`${hubUrl}/api/hub/session/${encodeURIComponent(sessionId)}`, {
+				headers: hubFetchHeaders(),
+				signal: AbortSignal.timeout(10_000),
+			});
+			if (resp.status === 404) {
+				tui.fatal(`Session not found: ${sessionId}`, ErrorCode.RESOURCE_NOT_FOUND);
+				return;
+			}
+			if (resp.status === 410) {
+				tui.fatal(`Session has shut down: ${sessionId}`, ErrorCode.RESOURCE_NOT_FOUND);
+				return;
+			}
+			if (!resp.ok) {
+				tui.fatal(
+					`Hub returned ${resp.status}: ${resp.statusText}. Is the Coder Hub running at ${hubUrl}?`,
+					ErrorCode.API_ERROR
+				);
+				return;
+			}
+			data = (await resp.json()) as typeof data;
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			tui.fatal(
+				`Could not connect to Coder Hub at ${hubUrl}: ${msg}\n\nSet AGENTUITY_CODER_HUB_URL or start the Hub with: bun run dev`,
+				ErrorCode.NETWORK_ERROR
+			);
+			return;
+		}
+
+		if (options.json) {
+			return data;
+		}
+
+		// Header
+		const label = data.label || data.sessionId;
+		console.log();
+		console.log(`  Session: ${label} (${data.sessionId})`);
+		const parts = [`Status: ${data.status}`, `Mode: ${data.mode}`];
+		if (data.context.branch) parts.push(`Branch: ${data.context.branch}`);
+		console.log(`  ${parts.join(' | ')}`);
+		console.log(`  Created: ${data.createdAt}`);
+
+		// Participants
+		console.log();
+		console.log('  Participants:');
+		if (data.participants.length === 0) {
+			console.log('    (none)');
+		} else {
+			for (const p of data.participants) {
+				const idle = p.idle ? '  (idle)' : '';
+				const connected = p.connectedAt
+					? `  connected ${formatRelativeTime(p.connectedAt)}`
+					: '';
+				console.log(
+					`    ${p.id.padEnd(12)} ${p.role.padEnd(10)} ${p.transport}${connected}${idle}`
+				);
+			}
+		}
+
+		// Tasks
+		if (data.tasks.length > 0) {
+			console.log();
+			console.log('  Tasks:');
+			for (const t of data.tasks) {
+				const dur = t.duration ? formatDuration(t.duration) : '-';
+				const prompt = t.prompt.length > 40 ? t.prompt.slice(0, 37) + '...' : t.prompt;
+				console.log(
+					`    ${t.taskId.padEnd(10)} ${t.agent.padEnd(10)} ${t.status.padEnd(10)} ${prompt.padEnd(42)} ${dur}`
+				);
+			}
+		}
+
+		// Agent Activity
+		const agents = Object.values(data.agentActivity);
+		if (agents.length > 0) {
+			console.log();
+			console.log('  Agent Activity:');
+			for (const a of agents) {
+				const tool = a.currentTool
+					? `${a.currentTool} (${a.toolCallCount} calls)`
+					: `${a.toolCallCount} calls`;
+				const lastAct = a.lastActivity
+					? formatRelativeTime(new Date(a.lastActivity).toISOString())
+					: '-';
+				console.log(
+					`    ${a.name.padEnd(12)} ${a.status.padEnd(8)} ${tool.padEnd(28)} last: ${lastAct}`
+				);
+			}
+		}
+
+		console.log();
+
+		return data;
+	},
+});

package/src/cmd/coder/list.ts

@@ -0,0 +1,143 @@
+import { z } from 'zod';
+import { createSubcommand } from '../../types';
+import * as tui from '../../tui';
+import { getCommand } from '../../command-prefix';
+import { ErrorCode } from '../../errors';
+import { resolveHubUrl, hubFetchHeaders } from './hub-url';
+
+function formatRelativeTime(isoDate: string): string {
+	const diffMs = Date.now() - new Date(isoDate).getTime();
+	const seconds = Math.floor(diffMs / 1000);
+	if (seconds < 60) return `${seconds}s ago`;
+	const minutes = Math.floor(seconds / 60);
+	if (minutes < 60) return `${minutes}m ago`;
+	const hours = Math.floor(minutes / 60);
+	if (hours < 24) return `${hours}h ago`;
+	const days = Math.floor(hours / 24);
+	return `${days}d ago`;
+}
+
+const SessionListResponseSchema = z.array(
+	z.object({
+		sessionId: z.string().describe('Session ID'),
+		label: z.string().describe('Human-readable session label'),
+		status: z.string().describe('Session status'),
+		mode: z.string().describe('Session mode (sandbox or tui)'),
+		createdAt: z.string().describe('Creation timestamp'),
+		taskCount: z.number().describe('Number of tasks'),
+		subAgentCount: z.number().describe('Number of sub-agents'),
+		observerCount: z.number().describe('Number of observers'),
+		participantCount: z.number().describe('Total participant count'),
+	})
+);
+
+export const listSubcommand = createSubcommand({
+	name: 'list',
+	description: 'List active Coder Hub sessions',
+	tags: ['read-only', 'fast', 'requires-auth'],
+	examples: [
+		{
+			command: getCommand('coder ls'),
+			description: 'List all active sessions',
+		},
+		{
+			command: getCommand('coder list --json'),
+			description: 'List sessions as JSON',
+		},
+	],
+	aliases: ['ls'],
+	idempotent: true,
+	schema: {
+		options: z.object({
+			hubUrl: z.string().optional().describe('Hub URL override'),
+		}),
+		response: SessionListResponseSchema,
+	},
+	async handler(ctx) {
+		const { options, opts } = ctx;
+		const hubUrl = await resolveHubUrl(opts?.hubUrl);
+
+		if (!hubUrl) {
+			tui.fatal(
+				'Could not find a running Coder Hub.\n\nEither:\n  - Start the Hub with: bun run dev\n  - Set AGENTUITY_CODER_HUB_URL environment variable\n  - Pass --hub-url flag',
+				ErrorCode.NETWORK_ERROR
+			);
+			return [];
+		}
+
+		let data: {
+			sessions: {
+				websocket: Array<{
+					sessionId: string;
+					label: string;
+					status: string;
+					mode: string;
+					createdAt: string;
+					taskCount: number;
+					subAgentCount: number;
+					observerCount: number;
+					participantCount: number;
+				}>;
+				sandbox: Array<Record<string, unknown>>;
+			};
+			total: number;
+		};
+
+		try {
+			const resp = await fetch(`${hubUrl}/api/hub/sessions`, {
+				headers: hubFetchHeaders(),
+				signal: AbortSignal.timeout(10_000),
+			});
+			if (!resp.ok) {
+				tui.fatal(
+					`Hub returned ${resp.status}: ${resp.statusText}. Is the Coder Hub running at ${hubUrl}?`,
+					ErrorCode.API_ERROR
+				);
+				return [];
+			}
+			data = (await resp.json()) as typeof data;
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			tui.fatal(
+				`Could not connect to Coder Hub at ${hubUrl}: ${msg}\n\nSet AGENTUITY_CODER_HUB_URL or start the Hub with: bun run dev`,
+				ErrorCode.NETWORK_ERROR
+			);
+			return [];
+		}
+
+		const sessions = data.sessions.websocket;
+
+		if (options.json) {
+			return sessions;
+		}
+
+		if (sessions.length === 0) {
+			tui.info('No active Coder Hub sessions.');
+			return [];
+		}
+
+		const tableData = sessions.map((s) => ({
+			'Session ID': s.sessionId.length > 20 ? s.sessionId.slice(0, 17) + '...' : s.sessionId,
+			Label: s.label || '-',
+			Status: s.status,
+			Mode: s.mode,
+			Observers: String(s.observerCount),
+			Agents: String(s.subAgentCount),
+			Tasks: String(s.taskCount),
+			Created: formatRelativeTime(s.createdAt),
+		}));
+
+		tui.table(tableData, [
+			{ name: 'Session ID', alignment: 'left' },
+			{ name: 'Label', alignment: 'left' },
+			{ name: 'Status', alignment: 'center' },
+			{ name: 'Mode', alignment: 'center' },
+			{ name: 'Observers', alignment: 'right' },
+			{ name: 'Agents', alignment: 'right' },
+			{ name: 'Tasks', alignment: 'right' },
+			{ name: 'Created', alignment: 'right' },
+		]);
+
+		return sessions;
+	},
+});