@contractspec/example.agent-console 3.7.7 → 3.8.2

package/src/ui/AgentDashboard.sandbox.test.tsx

@@ -0,0 +1,312 @@
+import { afterEach, beforeAll, describe, expect, it } from 'bun:test';
+import {
+	type TemplateDefinition,
+	TemplateRuntimeContext,
+	type TemplateRuntimeContextValue,
+} from '@contractspec/lib.example-shared-ui';
+import Window from 'happy-dom/lib/window/Window.js';
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import type { AgentHandlers } from '../handlers/agent.handlers';
+import {
+	AGENT_CONSOLE_DEMO_ORGANIZATION_ID,
+	createAgentConsoleDemoHandlers,
+} from '../shared';
+import { AgentDashboard } from './AgentDashboard';
+
+const PROJECT_ID = 'agent-console-sandbox-smoke';
+const TEMPLATE: TemplateDefinition = {
+	id: 'agent-console',
+	name: 'Agent Console',
+	description: 'Deterministic sandbox smoke test template.',
+	category: 'ai',
+	complexity: 'intermediate',
+	icon: '🤖',
+	features: ['agents', 'runs', 'tools', 'metrics'],
+	tags: ['sandbox', 'smoke'],
+	schema: { models: ['Agent', 'Run', 'Tool'], contracts: [] },
+	components: {
+		list: 'AgentListView',
+		detail: 'RunListView',
+		form: 'CreateAgentModal',
+	},
+};
+
+beforeAll(() => {
+	const windowInstance = new Window({
+		url: 'https://sandbox.contractspec.local/sandbox',
+	});
+	Object.defineProperty(windowInstance, 'SyntaxError', {
+		value: SyntaxError,
+		configurable: true,
+	});
+	Object.assign(globalThis, {
+		window: windowInstance,
+		document: windowInstance.document,
+		navigator: windowInstance.navigator,
+		HTMLElement: windowInstance.HTMLElement,
+		HTMLButtonElement: windowInstance.HTMLButtonElement,
+		HTMLInputElement: windowInstance.HTMLInputElement,
+		HTMLTextAreaElement: windowInstance.HTMLTextAreaElement,
+		Node: windowInstance.Node,
+		Event: windowInstance.Event,
+		MouseEvent: windowInstance.MouseEvent,
+		KeyboardEvent: windowInstance.KeyboardEvent,
+		MutationObserver: windowInstance.MutationObserver,
+		getComputedStyle: windowInstance.getComputedStyle.bind(windowInstance),
+		requestAnimationFrame: (callback: FrameRequestCallback) =>
+			setTimeout(() => callback(Date.now()), 0),
+		cancelAnimationFrame: (id: number) => clearTimeout(id),
+		IS_REACT_ACT_ENVIRONMENT: true,
+	});
+});
+
+afterEach(() => {
+	document.body.innerHTML = '';
+});
+
+function createContextValue(
+	handlers: AgentHandlers
+): TemplateRuntimeContextValue<{ agent: AgentHandlers }> {
+	return {
+		template: TEMPLATE,
+		runtime: {},
+		installer: {
+			install: async () => {},
+			saveToStudio: async () => ({ projectId: PROJECT_ID, status: 'saved' }),
+		},
+		client: {} as never,
+		templateId: TEMPLATE.id,
+		projectId: PROJECT_ID,
+		engine: {} as never,
+		fetchData: async () => ({ data: null }),
+		handlers: { agent: handlers },
+	};
+}
+
+async function renderDashboard() {
+	const container = document.createElement('div');
+	document.body.append(container);
+	const root: Root = createRoot(container);
+	const handlers = createAgentConsoleDemoHandlers({
+		projectId: PROJECT_ID,
+		organizationId: AGENT_CONSOLE_DEMO_ORGANIZATION_ID,
+		idFactory: (() => {
+			const counters = { agent: 0, run: 0 };
+			return (kind: 'agent' | 'run') => `${kind}-sandbox-${++counters[kind]}`;
+		})(),
+	});
+
+	await act(async () => {
+		root.render(
+			<TemplateRuntimeContext.Provider value={createContextValue(handlers)}>
+				<AgentDashboard />
+			</TemplateRuntimeContext.Provider>
+		);
+	});
+
+	return { container, root };
+}
+
+async function waitFor(assertion: () => boolean, timeoutMs = 3000) {
+	const startedAt = Date.now();
+	while (Date.now() - startedAt < timeoutMs) {
+		if (assertion()) {
+			return;
+		}
+		await act(async () => {
+			await new Promise((resolve) => setTimeout(resolve, 25));
+		});
+	}
+	throw new Error('Timed out waiting for dashboard state.');
+}
+
+function findButton(container: HTMLElement, label: string) {
+	return [...container.getElementsByTagName('button')].find((element) =>
+		element.textContent?.includes(label)
+	);
+}
+
+function findAgentCard(container: HTMLElement, name: string) {
+	return [...container.getElementsByTagName('*')].find(
+		(element) =>
+			element.getAttribute('role') === 'button' &&
+			element.textContent?.includes(name)
+	);
+}
+
+function getReactProp<T>(element: Element, propName: string): T | undefined {
+	const record = element as unknown as Record<string, unknown>;
+	const reactPropsKey = Object.keys(record).find((key) =>
+		key.startsWith('__reactProps$')
+	);
+	if (!reactPropsKey) {
+		return undefined;
+	}
+	const props = record[reactPropsKey];
+	if (typeof props !== 'object' || props === null || !(propName in props)) {
+		return undefined;
+	}
+	const value = (props as Record<string, unknown>)[propName];
+	return value as T | undefined;
+}
+
+async function click(element: Element | null | undefined) {
+	if (!element) {
+		throw new Error('Expected clickable element.');
+	}
+	const onPress = getReactProp<(() => void) | undefined>(element, 'onPress');
+	const onClick = getReactProp<((event: MouseEvent) => void) | undefined>(
+		element,
+		'onClick'
+	);
+	await act(async () => {
+		if (typeof onPress === 'function') {
+			onPress();
+			return;
+		}
+		if (typeof onClick === 'function') {
+			onClick(new MouseEvent('click', { bubbles: true }));
+			return;
+		}
+		if ('click' in element && typeof element.click === 'function') {
+			element.click();
+			return;
+		}
+		element.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+	});
+}
+
+async function fill(selector: string, value: string) {
+	const element = document.querySelector<
+		HTMLInputElement | HTMLTextAreaElement
+	>(selector);
+	if (!element) {
+		throw new Error(`Missing form field ${selector}.`);
+	}
+	const valueSetter = Object.getOwnPropertyDescriptor(
+		Object.getPrototypeOf(element),
+		'value'
+	)?.set;
+	if (!valueSetter) {
+		throw new Error(`Missing value setter for ${selector}.`);
+	}
+	const onChange = getReactProp<
+		(event: {
+			target: { value: string };
+			currentTarget: { value: string };
+		}) => void
+	>(element, 'onChange');
+	await act(async () => {
+		valueSetter.call(element, value);
+		onChange?.({
+			target: { value },
+			currentTarget: { value },
+		});
+		if (!onChange) {
+			element.dispatchEvent(new Event('input', { bubbles: true }));
+			element.dispatchEvent(new Event('change', { bubbles: true }));
+		}
+	});
+}
+
+describe('AgentDashboard sandbox smoke', () => {
+	it('loads seeded state, renders tabs, creates an agent, and executes a run', async () => {
+		const { container, root } = await renderDashboard();
+		await waitFor(
+			() => container.textContent?.includes('AI Agent Console') === true
+		);
+		await waitFor(
+			() =>
+				container.textContent?.includes(
+					'Affichage de 1 à 3 sur 5 résultats'
+				) === true
+		);
+
+		expect(container.textContent).toContain('Runs');
+		expect(container.textContent).toContain('Agents');
+		expect(container.textContent).toContain('Tools');
+		expect(container.textContent).toContain('Metrics');
+		expect(container.textContent).toContain('Run History');
+
+		await click(findButton(container, 'Tools'));
+		await waitFor(
+			() => container.textContent?.includes('Total Tools') === true
+		);
+		await click(findButton(container, 'Metrics'));
+		await waitFor(
+			() => container.textContent?.includes('Usage Analytics') === true
+		);
+		await click(findButton(container, 'Agents'));
+		await waitFor(() => container.textContent?.includes('Total: 4') === true);
+
+		await click(findButton(container, 'New Agent'));
+		await waitFor(
+			() => document.body.textContent?.includes('Create New Agent') === true
+		);
+		await fill('#agent-name', 'Paris Meetup UI Agent');
+		await fill(
+			'#agent-description',
+			'Smoke test agent for the sandbox walkthrough.'
+		);
+		await click(findButton(document.body, 'Create Agent'));
+		await click(findButton(container, 'Runs'));
+		await waitFor(
+			() =>
+				container.textContent?.includes(
+					'Affichage de 1 à 3 sur 5 résultats'
+				) === true
+		);
+		await click(findButton(container, 'Agents'));
+		await waitFor(
+			() => container.textContent?.includes('Paris Meetup UI Agent') === true
+		);
+		await waitFor(() => container.textContent?.includes('Total: 5') === true);
+
+		const agentCard = findAgentCard(container, 'Paris Meetup UI Agent');
+		await click(agentCard);
+		await waitFor(
+			() => document.body.textContent?.includes('Activate Agent') === true
+		);
+		await click(findButton(document.body, 'Activate Agent'));
+		await click(findButton(container, 'Runs'));
+		await waitFor(
+			() => container.textContent?.includes('Run History') === true
+		);
+		await click(findButton(container, 'Agents'));
+		await waitFor(
+			() =>
+				findAgentCard(
+					container,
+					'Paris Meetup UI Agent'
+				)?.textContent?.includes('ACTIVE') === true
+		);
+
+		const activeAgentCard = findAgentCard(container, 'Paris Meetup UI Agent');
+		await click(activeAgentCard);
+		await waitFor(
+			() => document.body.textContent?.includes('Execute Agent') === true
+		);
+		await click(findButton(document.body, 'Execute Agent'));
+		await waitFor(
+			() => document.body.textContent?.includes('Message *') === true
+		);
+		await fill('#execute-message', 'Summarize the meetup smoke test.');
+		await click(findButton(document.body, 'Execute'));
+
+		await click(findButton(container, 'Runs'));
+		await waitFor(
+			() =>
+				container.textContent?.includes(
+					'Affichage de 1 à 3 sur 6 résultats'
+				) === true
+		);
+		await waitFor(
+			() => container.textContent?.includes('Paris Meetup UI Agent') === true
+		);
+
+		await act(async () => {
+			root.unmount();
+		});
+	});
+});

package/src/ui/AgentDashboard.tsx

@@ -17,6 +17,7 @@ import {
  * - ExecuteAgentCommand -> Execute agent via modal
  */
 import { useCallback, useMemo, useState } from 'react';
+import { AgentVisualizationOverview } from './AgentDashboard.visualizations';
 import { type Agent, useAgentList } from './hooks/useAgentList';
 import { useAgentMutations } from './hooks/useAgentMutations';
 import { type RunMetrics, useRunList } from './hooks/useRunList';
@@ -34,7 +35,7 @@ export function AgentDashboard() {
 	const [selectedAgent, setSelectedAgent] = useState<Agent | null>(null);
 	const [isAgentActionsOpen, setIsAgentActionsOpen] = useState(false);
 
-	const { metrics, refetch: refetchRuns } = useRunList();
+	const { data: runData, metrics, refetch: refetchRuns } = useRunList();
 	const { refetch: refetchAgents } = useAgentList();
 
 	const mutations = useAgentMutations({
@@ -115,6 +116,8 @@ export function AgentDashboard() {
 				))}
 			</StatCardGroup>
 
+			<AgentVisualizationOverview runs={runData?.items ?? []} />
+
 			{/* Navigation Tabs */}
 			<nav className="flex gap-1 rounded-lg bg-muted p-1" role="tablist">
 				{tabs.map((tab) => (

package/src/ui/AgentDashboard.visualizations.tsx

@@ -0,0 +1,35 @@
+'use client';
+
+import {
+	VisualizationCard,
+	VisualizationGrid,
+} from '@contractspec/lib.design-system';
+import { createAgentVisualizationItems } from '../visualizations';
+import type { Run } from './hooks/useRunList';
+
+export function AgentVisualizationOverview({ runs }: { runs: Run[] }) {
+	const items = createAgentVisualizationItems(runs);
+
+	return (
+		<section className="space-y-3">
+			<div>
+				<h3 className="font-semibold text-lg">Operational Visualizations</h3>
+				<p className="text-muted-foreground text-sm">
+					Contract-backed charts derived from recent run activity.
+				</p>
+			</div>
+			<VisualizationGrid>
+				{items.map((item) => (
+					<VisualizationCard
+						key={item.key}
+						data={item.data}
+						description={item.description}
+						height={item.height}
+						spec={item.spec}
+						title={item.title}
+					/>
+				))}
+			</VisualizationGrid>
+		</section>
+	);
+}

package/src/ui/hooks/useAgentMutations.ts

@@ -15,6 +15,7 @@ import type {
 	Run,
 	UpdateAgentInput,
 } from '../../handlers/agent.handlers';
+import { AGENT_CONSOLE_DEMO_ORGANIZATION_ID } from '../../shared/demo-runtime-seed';
 
 export interface MutationState<T> {
 	loading: boolean;
@@ -27,6 +28,13 @@ export interface UseAgentMutationsOptions {
 	onError?: (error: Error) => void;
 }
 
+function normalizeMutationError(
+	error: unknown,
+	fallbackMessage: string
+): Error {
+	return error instanceof Error ? error : new Error(fallbackMessage);
+}
+
 export function useAgentMutations(options: UseAgentMutationsOptions = {}) {
 	const { handlers, projectId } = useTemplateRuntime<{
 		agent: AgentHandlers;
@@ -60,17 +68,16 @@ export function useAgentMutations(options: UseAgentMutationsOptions = {}) {
 			try {
 				const result = await agent.createAgent(input, {
 					projectId,
-					organizationId: 'demo-org',
+					organizationId: AGENT_CONSOLE_DEMO_ORGANIZATION_ID,
 				});
 				setCreateState({ loading: false, error: null, data: result });
 				options.onSuccess?.();
 				return result;
 			} catch (err) {
-				const error =
-					err instanceof Error ? err : new Error('Failed to create agent');
+				const error = normalizeMutationError(err, 'Failed to create agent');
 				setCreateState({ loading: false, error, data: null });
 				options.onError?.(error);
-				return null;
+				throw error;
 			}
 		},
 		[agent, projectId, options]
@@ -88,11 +95,10 @@ export function useAgentMutations(options: UseAgentMutationsOptions = {}) {
 				options.onSuccess?.();
 				return result;
 			} catch (err) {
-				const error =
-					err instanceof Error ? err : new Error('Failed to update agent');
+				const error = normalizeMutationError(err, 'Failed to update agent');
 				setUpdateState({ loading: false, error, data: null });
 				options.onError?.(error);
-				return null;
+				throw error;
 			}
 		},
 		[agent, options]
@@ -141,17 +147,19 @@ export function useAgentMutations(options: UseAgentMutationsOptions = {}) {
 				const result = await agent.executeAgent({
 					agentId: input.agentId,
 					message: input.message,
-					context: { projectId, organizationId: 'demo-org' },
+					context: {
+						projectId,
+						organizationId: AGENT_CONSOLE_DEMO_ORGANIZATION_ID,
+					},
 				});
 				setExecuteState({ loading: false, error: null, data: result });
 				options.onSuccess?.();
 				return result;
 			} catch (err) {
-				const error =
-					err instanceof Error ? err : new Error('Failed to execute agent');
+				const error = normalizeMutationError(err, 'Failed to execute agent');
 				setExecuteState({ loading: false, error, data: null });
 				options.onError?.(error);
-				return null;
+				throw error;
 			}
 		},
 		[agent, projectId, options]

package/src/ui/hooks/useRunList.ts

@@ -5,6 +5,7 @@
  */
 
 import { useTemplateRuntime } from '@contractspec/lib.example-shared-ui';
+import type { ContractTableSort } from '@contractspec/lib.presentation-runtime-core';
 import { useCallback, useEffect, useState } from 'react';
 import type {
 	AgentHandlers,
@@ -22,6 +23,9 @@ export interface UseRunListOptions {
 	agentId?: string;
 	status?: Run['status'] | 'all';
 	limit?: number;
+	pageIndex?: number;
+	pageSize?: number;
+	sorting?: ContractTableSort[];
 }
 
 export function useRunList(options: UseRunListOptions = {}) {
@@ -34,7 +38,11 @@ export function useRunList(options: UseRunListOptions = {}) {
 	const [metrics, setMetrics] = useState<RunMetrics | null>(null);
 	const [loading, setLoading] = useState(true);
 	const [error, setError] = useState<Error | null>(null);
-	const [page, setPage] = useState(1);
+	const [internalPageIndex, setInternalPageIndex] = useState(0);
+
+	const pageSize = options.pageSize ?? options.limit ?? 20;
+	const pageIndex = options.pageIndex ?? internalPageIndex;
+	const [sort] = options.sorting ?? [];
 
 	const fetchData = useCallback(async () => {
 		setLoading(true);
@@ -46,14 +54,21 @@ export function useRunList(options: UseRunListOptions = {}) {
 					projectId,
 					agentId: options.agentId,
 					status: options.status === 'all' ? undefined : options.status,
-					limit: options.limit ?? 20,
-					offset: (page - 1) * (options.limit ?? 20),
+					sortBy: sort?.id as
+						| 'queuedAt'
+						| 'totalTokens'
+						| 'durationMs'
+						| 'estimatedCostUsd'
+						| 'status'
+						| 'agentName'
+						| undefined,
+					sortDirection: sort ? (sort.desc ? 'desc' : 'asc') : undefined,
+					limit: pageSize,
+					offset: pageIndex * pageSize,
 				}),
 				agent.getRunMetrics({
 					projectId,
 					agentId: options.agentId,
-					startDate: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000), // 30 days ago
-					endDate: new Date(),
 				}),
 			]);
 			setData(runsResult);
@@ -63,20 +78,37 @@ export function useRunList(options: UseRunListOptions = {}) {
 		} finally {
 			setLoading(false);
 		}
-	}, [agent, projectId, options.agentId, options.status, options.limit, page]);
+	}, [
+		agent,
+		pageIndex,
+		pageSize,
+		projectId,
+		options.agentId,
+		options.status,
+		sort?.desc,
+		sort?.id,
+	]);
 
 	useEffect(() => {
 		fetchData();
 	}, [fetchData]);
 
+	const hasControlledPagination = options.pageIndex !== undefined;
+
 	return {
 		data,
 		metrics,
 		loading,
 		error,
-		page,
+		page: pageIndex + 1,
+		pageIndex,
+		pageSize,
 		refetch: fetchData,
-		nextPage: () => setPage((p) => p + 1),
-		prevPage: () => page > 1 && setPage((p) => p - 1),
+		nextPage: hasControlledPagination
+			? undefined
+			: () => setInternalPageIndex((current) => current + 1),
+		prevPage: hasControlledPagination
+			? undefined
+			: () => setInternalPageIndex((current) => Math.max(0, current - 1)),
 	};
 }

package/src/ui/renderers/agent-list.markdown.ts

@@ -5,13 +5,20 @@
  */
 
 import {
-	type AgentSummary,
-	mockListAgentsHandler,
-} from '@contractspec/example.agent-console/handlers';
+	AGENT_CONSOLE_DEMO_ORGANIZATION_ID,
+	AGENT_CONSOLE_DEMO_PROJECT_ID,
+	createAgentConsoleDemoHandlers,
+} from '@contractspec/example.agent-console/shared';
 import type { PresentationSpec } from '@contractspec/lib.contracts-spec/presentations';
 import type { PresentationRenderer } from '@contractspec/lib.contracts-spec/presentations/transform-engine';
 
-type Agent = AgentSummary;
+interface AgentListItem {
+	name: string;
+	description?: string;
+	status: string;
+	modelProvider: string;
+	modelName: string;
+}
 
 /**
  * Markdown renderer for agent-console.agent.list presentation
@@ -22,7 +29,7 @@ export const agentListMarkdownRenderer: PresentationRenderer<{
 	body: string;
 }> = {
 	target: 'markdown',
-	render: async (desc: PresentationSpec) => {
+	render: async (desc: PresentationSpec, ctx) => {
 		// Only handle AgentListView
 		if (
 			desc.source.type !== 'component' ||
@@ -31,12 +38,24 @@ export const agentListMarkdownRenderer: PresentationRenderer<{
 			throw new Error('agentListMarkdownRenderer: not AgentListView');
 		}
 
-		// Fetch data using mock handler
-		const data = await mockListAgentsHandler({
-			organizationId: 'demo-org',
-			limit: 50,
-			offset: 0,
-		});
+		const data: {
+			items: AgentListItem[];
+			total: number;
+			hasMore: boolean;
+		} = Array.isArray(ctx?.data)
+			? {
+					items: ctx.data as AgentListItem[],
+					total: ctx.data.length,
+					hasMore: false,
+				}
+			: await createAgentConsoleDemoHandlers({
+					projectId: AGENT_CONSOLE_DEMO_PROJECT_ID,
+				}).listAgents({
+					projectId: AGENT_CONSOLE_DEMO_PROJECT_ID,
+					organizationId: AGENT_CONSOLE_DEMO_ORGANIZATION_ID,
+					limit: 50,
+					offset: 0,
+				});
 
 		// Generate markdown
 		const lines: string[] = [
@@ -51,7 +70,7 @@ export const agentListMarkdownRenderer: PresentationRenderer<{
 		];
 
 		// Group by status
-		const byStatus: Record<string, Agent[]> = {};
+		const byStatus: Record<string, AgentListItem[]> = {};
 		for (const agent of data.items) {
 			const status = agent.status;
 			if (byStatus[status]) {