@contractspec/example.agent-console 3.7.7 → 3.8.4

package/src/shared/demo-runtime-seed.ts

@@ -0,0 +1,139 @@
+import type { Agent, Run, RunMetrics, Tool } from '../handlers/agent.handlers';
+import { MOCK_AGENTS } from './mock-agents';
+import { MOCK_RUNS } from './mock-runs';
+import { MOCK_TOOLS } from './mock-tools';
+
+export const AGENT_CONSOLE_DEMO_ORGANIZATION_ID = 'demo-org';
+export const AGENT_CONSOLE_DEMO_PROJECT_ID = 'agent-console-demo';
+
+export type DemoAgentRecord = Agent & { slug: string };
+
+export function slugify(name: string): string {
+	return name
+		.toLowerCase()
+		.trim()
+		.replace(/[^a-z0-9]+/g, '-')
+		.replace(/^-+|-+$/g, '');
+}
+
+export function cloneAgent(agent: DemoAgentRecord): Agent {
+	return { ...agent };
+}
+
+export function cloneTool(tool: Tool): Tool {
+	return { ...tool };
+}
+
+export function cloneRun(run: Run): Run {
+	return { ...run };
+}
+
+export function createDefaultNow(): () => Date {
+	let tick = 0;
+	const base = Date.parse('2026-03-20T09:00:00.000Z');
+	return () => new Date(base + tick++ * 60_000);
+}
+
+function normalizeProvider(provider: string): string {
+	return provider.toLowerCase();
+}
+
+function normalizeRunStatus(status: string): Run['status'] {
+	return status === 'IN_PROGRESS' ? 'RUNNING' : (status as Run['status']);
+}
+
+export function createSeedState(
+	projectId: string,
+	organizationId: string
+): {
+	agents: DemoAgentRecord[];
+	tools: Tool[];
+	runs: Run[];
+} {
+	const agents = MOCK_AGENTS.map((agent) => ({
+		id: agent.id,
+		projectId,
+		organizationId,
+		name: agent.name,
+		slug: agent.slug,
+		description: agent.description,
+		modelProvider: normalizeProvider(agent.modelProvider),
+		modelName: agent.modelName,
+		systemPrompt: agent.systemPrompt,
+		temperature:
+			typeof agent.modelConfig?.temperature === 'number'
+				? agent.modelConfig.temperature
+				: 0.4,
+		maxTokens: 8192,
+		status: agent.status,
+		createdAt: agent.createdAt,
+		updatedAt: agent.updatedAt,
+	}));
+
+	const tools = MOCK_TOOLS.map((tool) => ({
+		id: tool.id,
+		projectId,
+		organizationId,
+		name: tool.name,
+		description: tool.description,
+		version: tool.version,
+		category: tool.category,
+		status: tool.status,
+		inputSchema: JSON.stringify(tool.parametersSchema),
+		outputSchema: tool.outputSchema
+			? JSON.stringify(tool.outputSchema)
+			: undefined,
+		endpoint:
+			typeof tool.implementationConfig?.url === 'string'
+				? tool.implementationConfig.url
+				: undefined,
+		createdAt: tool.createdAt,
+		updatedAt: tool.updatedAt,
+	}));
+
+	const agentNames = new Map(
+		agents.map((agent) => [agent.id, agent.name] as const)
+	);
+	const runs = MOCK_RUNS.map((run) => ({
+		id: run.id,
+		projectId,
+		agentId: run.agentId,
+		agentName: agentNames.get(run.agentId) ?? run.agentName ?? 'Unknown agent',
+		status: normalizeRunStatus(run.status),
+		input: JSON.stringify(run.input),
+		output: run.output ? JSON.stringify(run.output) : undefined,
+		totalTokens: run.totalTokens,
+		promptTokens: run.promptTokens,
+		completionTokens: run.completionTokens,
+		estimatedCostUsd: run.estimatedCostUsd ?? 0,
+		durationMs: run.durationMs,
+		errorMessage: run.errorMessage,
+		queuedAt: run.queuedAt,
+		startedAt: run.startedAt,
+		completedAt: run.completedAt,
+	}));
+
+	return { agents, tools, runs };
+}
+
+export function summarizeRunMetrics(runs: Run[]): RunMetrics {
+	const totalRuns = runs.length;
+	const completedRuns = runs.filter((run) => run.status === 'COMPLETED').length;
+	const completedDurations = runs
+		.map((run) => run.durationMs)
+		.filter((duration): duration is number => typeof duration === 'number');
+
+	return {
+		totalRuns,
+		successRate: totalRuns === 0 ? 0 : completedRuns / totalRuns,
+		averageDurationMs:
+			completedDurations.length === 0
+				? 0
+				: Math.round(
+						completedDurations.reduce((sum, duration) => sum + duration, 0) /
+							completedDurations.length
+					),
+		totalTokens: runs.reduce((sum, run) => sum + run.totalTokens, 0),
+		totalCostUsd: runs.reduce((sum, run) => sum + run.estimatedCostUsd, 0),
+	};
+}

package/src/shared/demo-runtime.test.ts

@@ -0,0 +1,169 @@
+import { describe, expect, it } from 'bun:test';
+import {
+	AGENT_CONSOLE_DEMO_ORGANIZATION_ID,
+	AGENT_CONSOLE_DEMO_PROJECT_ID,
+	createAgentConsoleDemoHandlers,
+} from './index';
+import { MOCK_AGENTS } from './mock-agents';
+import { MOCK_RUNS } from './mock-runs';
+import { MOCK_TOOLS } from './mock-tools';
+
+describe('createAgentConsoleDemoHandlers', () => {
+	it('lists seeded agents, tools, and runs', async () => {
+		const handlers = createAgentConsoleDemoHandlers({
+			projectId: AGENT_CONSOLE_DEMO_PROJECT_ID,
+		});
+		const [agents, tools, runs] = await Promise.all([
+			handlers.listAgents({
+				projectId: AGENT_CONSOLE_DEMO_PROJECT_ID,
+				organizationId: AGENT_CONSOLE_DEMO_ORGANIZATION_ID,
+				limit: 10,
+			}),
+			handlers.listTools({
+				projectId: AGENT_CONSOLE_DEMO_PROJECT_ID,
+				organizationId: AGENT_CONSOLE_DEMO_ORGANIZATION_ID,
+				limit: 10,
+			}),
+			handlers.listRuns({
+				projectId: AGENT_CONSOLE_DEMO_PROJECT_ID,
+				limit: 10,
+			}),
+		]);
+
+		expect(agents.total).toBe(MOCK_AGENTS.length);
+		expect(tools.total).toBe(MOCK_TOOLS.length);
+		expect(runs.total).toBe(MOCK_RUNS.length);
+		expect(agents.items[0]?.updatedAt).toBeInstanceOf(Date);
+		expect(runs.items[0]?.queuedAt).toBeInstanceOf(Date);
+	});
+
+	it('creates agents and rejects duplicate names or slugs', async () => {
+		const handlers = createAgentConsoleDemoHandlers({
+			projectId: AGENT_CONSOLE_DEMO_PROJECT_ID,
+		});
+		const created = await handlers.createAgent(
+			{
+				name: 'Paris Meetup Agent',
+				description: 'Deterministic meetup walkthrough agent',
+				systemPrompt: 'Stay deterministic.',
+			},
+			{
+				projectId: AGENT_CONSOLE_DEMO_PROJECT_ID,
+				organizationId: AGENT_CONSOLE_DEMO_ORGANIZATION_ID,
+			}
+		);
+
+		expect(created.id).toBe('agent-demo-5');
+		expect(created.name).toBe('Paris Meetup Agent');
+		expect(created.status).toBe('DRAFT');
+
+		await expect(
+			handlers.createAgent(
+				{
+					name: 'paris meetup agent',
+				},
+				{
+					projectId: AGENT_CONSOLE_DEMO_PROJECT_ID,
+					organizationId: AGENT_CONSOLE_DEMO_ORGANIZATION_ID,
+				}
+			)
+		).rejects.toThrow('AGENT_NAME_OR_SLUG_EXISTS');
+	});
+
+	it('updates agent status transitions', async () => {
+		const handlers = createAgentConsoleDemoHandlers({
+			projectId: AGENT_CONSOLE_DEMO_PROJECT_ID,
+		});
+		const created = await handlers.createAgent(
+			{
+				name: 'Status Transition Agent',
+			},
+			{
+				projectId: AGENT_CONSOLE_DEMO_PROJECT_ID,
+				organizationId: AGENT_CONSOLE_DEMO_ORGANIZATION_ID,
+			}
+		);
+
+		const active = await handlers.updateAgent({
+			id: created.id,
+			status: 'ACTIVE',
+		});
+		const paused = await handlers.updateAgent({
+			id: created.id,
+			status: 'PAUSED',
+		});
+
+		expect(active.status).toBe('ACTIVE');
+		expect(paused.status).toBe('PAUSED');
+		expect(paused.updatedAt.getTime()).toBeGreaterThan(
+			active.updatedAt.getTime()
+		);
+	});
+
+	it('executes active agents with deterministic run output', async () => {
+		const handlers = createAgentConsoleDemoHandlers({
+			projectId: AGENT_CONSOLE_DEMO_PROJECT_ID,
+		});
+		const created = await handlers.createAgent(
+			{
+				name: 'Execution Agent',
+				systemPrompt: 'Reply deterministically.',
+			},
+			{
+				projectId: AGENT_CONSOLE_DEMO_PROJECT_ID,
+				organizationId: AGENT_CONSOLE_DEMO_ORGANIZATION_ID,
+			}
+		);
+		await handlers.updateAgent({ id: created.id, status: 'ACTIVE' });
+
+		const run = await handlers.executeAgent({
+			agentId: created.id,
+			message: 'Summarize the meetup flow.',
+			context: {
+				projectId: AGENT_CONSOLE_DEMO_PROJECT_ID,
+				organizationId: AGENT_CONSOLE_DEMO_ORGANIZATION_ID,
+			},
+		});
+
+		expect(run.id).toBe('run-demo-6');
+		expect(run.status).toBe('COMPLETED');
+		expect(run.output).toContain(
+			'Deterministic demo reply from Execution Agent'
+		);
+		expect(run.totalTokens).toBe(run.promptTokens + run.completionTokens);
+	});
+
+	it('updates aggregate metrics after execution', async () => {
+		const handlers = createAgentConsoleDemoHandlers({
+			projectId: AGENT_CONSOLE_DEMO_PROJECT_ID,
+		});
+		const before = await handlers.getRunMetrics({
+			projectId: AGENT_CONSOLE_DEMO_PROJECT_ID,
+		});
+		const created = await handlers.createAgent(
+			{
+				name: 'Metrics Agent',
+			},
+			{
+				projectId: AGENT_CONSOLE_DEMO_PROJECT_ID,
+				organizationId: AGENT_CONSOLE_DEMO_ORGANIZATION_ID,
+			}
+		);
+		await handlers.updateAgent({ id: created.id, status: 'ACTIVE' });
+		await handlers.executeAgent({
+			agentId: created.id,
+			message: 'Verify metrics.',
+			context: {
+				projectId: AGENT_CONSOLE_DEMO_PROJECT_ID,
+				organizationId: AGENT_CONSOLE_DEMO_ORGANIZATION_ID,
+			},
+		});
+		const after = await handlers.getRunMetrics({
+			projectId: AGENT_CONSOLE_DEMO_PROJECT_ID,
+		});
+
+		expect(after.totalRuns).toBe(before.totalRuns + 1);
+		expect(after.totalTokens).toBeGreaterThan(before.totalTokens);
+		expect(after.totalCostUsd).toBeGreaterThan(before.totalCostUsd);
+	});
+});

package/src/shared/demo-runtime.ts

@@ -0,0 +1,260 @@
+import type {
+	Agent,
+	AgentHandlers,
+	CreateAgentInput,
+	ListAgentsInput,
+	ListAgentsOutput,
+	ListRunsInput,
+	ListRunsOutput,
+	ListToolsInput,
+	ListToolsOutput,
+	Run,
+	RunMetrics,
+	UpdateAgentInput,
+} from '../handlers/agent.handlers';
+import {
+	AGENT_CONSOLE_DEMO_ORGANIZATION_ID,
+	cloneAgent,
+	cloneRun,
+	cloneTool,
+	createDefaultNow,
+	createSeedState,
+	type DemoAgentRecord,
+	slugify,
+	summarizeRunMetrics,
+} from './demo-runtime-seed';
+
+export interface AgentConsoleDemoRuntimeOptions {
+	projectId: string;
+	organizationId?: string;
+	now?: () => Date;
+	idFactory?: (kind: 'agent' | 'run', nextIndex: number) => string;
+}
+
+export function createAgentConsoleDemoHandlers(
+	options: AgentConsoleDemoRuntimeOptions
+): AgentHandlers {
+	const projectId = options.projectId;
+	const organizationId =
+		options.organizationId ?? AGENT_CONSOLE_DEMO_ORGANIZATION_ID;
+	const now = options.now ?? createDefaultNow();
+	const state = createSeedState(projectId, organizationId);
+	let agentIndex = state.agents.length + 1;
+	let runIndex = state.runs.length + 1;
+
+	const nextId = (kind: 'agent' | 'run') => {
+		const nextIndex = kind === 'agent' ? agentIndex++ : runIndex++;
+		return options.idFactory?.(kind, nextIndex) ?? `${kind}-demo-${nextIndex}`;
+	};
+
+	return {
+		async listAgents(input: ListAgentsInput): Promise<ListAgentsOutput> {
+			const filtered = state.agents
+				.filter((agent) => agent.projectId === input.projectId)
+				.filter(
+					(agent) =>
+						!input.organizationId ||
+						agent.organizationId === input.organizationId
+				)
+				.filter(
+					(agent) =>
+						!input.status ||
+						input.status === 'all' ||
+						agent.status === input.status
+				)
+				.filter((agent) => {
+					if (!input.search) return true;
+					const query = input.search.toLowerCase();
+					return (
+						agent.name.toLowerCase().includes(query) ||
+						(agent.description ?? '').toLowerCase().includes(query)
+					);
+				})
+				.sort(
+					(left, right) => right.updatedAt.getTime() - left.updatedAt.getTime()
+				);
+			const limit = input.limit ?? 20;
+			const offset = input.offset ?? 0;
+			const items = filtered.slice(offset, offset + limit).map(cloneAgent);
+			return {
+				items,
+				total: filtered.length,
+				hasMore: offset + items.length < filtered.length,
+			};
+		},
+		async getAgent(id: string) {
+			const agent = state.agents.find((item) => item.id === id);
+			return agent ? cloneAgent(agent) : null;
+		},
+		async createAgent(
+			input: CreateAgentInput,
+			context: { projectId: string; organizationId: string }
+		): Promise<Agent> {
+			const name = input.name.trim();
+			const slug = slugify(name);
+			const duplicate = state.agents.find(
+				(agent) =>
+					agent.projectId === context.projectId &&
+					agent.organizationId === context.organizationId &&
+					(agent.slug === slug ||
+						agent.name.toLowerCase() === name.toLowerCase())
+			);
+			if (duplicate) throw new Error('AGENT_NAME_OR_SLUG_EXISTS');
+
+			const timestamp = now();
+			const agent: DemoAgentRecord = {
+				id: nextId('agent'),
+				projectId: context.projectId,
+				organizationId: context.organizationId,
+				name,
+				slug,
+				description: input.description,
+				modelProvider: input.modelProvider ?? 'openai',
+				modelName: input.modelName ?? 'gpt-5.4',
+				systemPrompt: input.systemPrompt,
+				temperature: input.temperature ?? 0.4,
+				maxTokens: input.maxTokens ?? 8192,
+				status: 'DRAFT',
+				createdAt: timestamp,
+				updatedAt: timestamp,
+			};
+			state.agents.unshift(agent);
+			return cloneAgent(agent);
+		},
+		async updateAgent(input: UpdateAgentInput): Promise<Agent> {
+			const agent = state.agents.find((item) => item.id === input.id);
+			if (!agent) throw new Error('AGENT_NOT_FOUND');
+			const nextName = input.name;
+			if (nextName && slugify(nextName) !== agent.slug) {
+				const duplicate = state.agents.find(
+					(item) =>
+						item.id !== agent.id &&
+						item.projectId === agent.projectId &&
+						item.organizationId === agent.organizationId &&
+						(item.slug === slugify(nextName) ||
+							item.name.toLowerCase() === nextName.toLowerCase())
+				);
+				if (duplicate) throw new Error('AGENT_NAME_OR_SLUG_EXISTS');
+				agent.slug = slugify(nextName);
+				agent.name = nextName;
+			}
+			if (input.description !== undefined)
+				agent.description = input.description;
+			if (input.status) agent.status = input.status;
+			agent.updatedAt = now();
+			return cloneAgent(agent);
+		},
+		async executeAgent(input: {
+			agentId: string;
+			message: string;
+			context?: { projectId: string; organizationId: string };
+		}): Promise<Run> {
+			const agent = state.agents.find((item) => item.id === input.agentId);
+			if (!agent) throw new Error('AGENT_NOT_FOUND');
+			if (agent.status !== 'ACTIVE') throw new Error('AGENT_NOT_ACTIVE');
+
+			const queuedAt = now();
+			const startedAt = now();
+			const completedAt = now();
+			const durationMs = 2200 + input.message.length * 12;
+			const promptTokens = 600 + input.message.length * 3;
+			const completionTokens = 240 + agent.name.length * 4;
+			const run: Run = {
+				id: nextId('run'),
+				projectId: input.context?.projectId ?? agent.projectId,
+				agentId: agent.id,
+				agentName: agent.name,
+				status: 'COMPLETED',
+				input: input.message,
+				output: `Deterministic demo reply from ${agent.name}: ${input.message}`,
+				totalTokens: promptTokens + completionTokens,
+				promptTokens,
+				completionTokens,
+				estimatedCostUsd: Number(
+					((promptTokens + completionTokens) / 1_000_000).toFixed(4)
+				),
+				durationMs,
+				queuedAt,
+				startedAt,
+				completedAt,
+			};
+			state.runs.unshift(run);
+			return cloneRun(run);
+		},
+		async listTools(input: ListToolsInput): Promise<ListToolsOutput> {
+			const filtered = state.tools
+				.filter((tool) => tool.projectId === input.projectId)
+				.filter(
+					(tool) =>
+						!input.organizationId ||
+						tool.organizationId === input.organizationId
+				)
+				.filter(
+					(tool) =>
+						!input.category ||
+						input.category === 'all' ||
+						tool.category === input.category
+				)
+				.filter(
+					(tool) =>
+						!input.status ||
+						input.status === 'all' ||
+						tool.status === input.status
+				)
+				.filter((tool) => {
+					if (!input.search) return true;
+					const query = input.search.toLowerCase();
+					return (
+						tool.name.toLowerCase().includes(query) ||
+						(tool.description ?? '').toLowerCase().includes(query)
+					);
+				})
+				.sort((left, right) => left.name.localeCompare(right.name));
+			const limit = input.limit ?? 50;
+			const offset = input.offset ?? 0;
+			const items = filtered.slice(offset, offset + limit).map(cloneTool);
+			return {
+				items,
+				total: filtered.length,
+				hasMore: offset + items.length < filtered.length,
+			};
+		},
+		async listRuns(input: ListRunsInput): Promise<ListRunsOutput> {
+			const filtered = state.runs
+				.filter((run) => run.projectId === input.projectId)
+				.filter((run) => !input.agentId || run.agentId === input.agentId)
+				.filter(
+					(run) =>
+						!input.status ||
+						input.status === 'all' ||
+						run.status === input.status
+				)
+				.sort(
+					(left, right) => right.queuedAt.getTime() - left.queuedAt.getTime()
+				);
+			const limit = input.limit ?? 20;
+			const offset = input.offset ?? 0;
+			const items = filtered.slice(offset, offset + limit).map(cloneRun);
+			return {
+				items,
+				total: filtered.length,
+				hasMore: offset + items.length < filtered.length,
+			};
+		},
+		async getRunMetrics(input: {
+			projectId: string;
+			agentId?: string;
+			startDate?: Date;
+			endDate?: Date;
+		}): Promise<RunMetrics> {
+			const filtered = state.runs.filter((run) => {
+				if (run.projectId !== input.projectId) return false;
+				if (input.agentId && run.agentId !== input.agentId) return false;
+				if (input.startDate && run.queuedAt < input.startDate) return false;
+				if (input.endDate && run.queuedAt > input.endDate) return false;
+				return true;
+			});
+			return summarizeRunMetrics(filtered);
+		},
+	};
+}

package/src/shared/index.ts

@@ -1,6 +1,17 @@
 /**
  * Shared utilities and mock data.
  */
+
+export {
+	type AgentConsoleDashboardData,
+	getAgentConsoleDashboardData,
+	getFallbackAgentConsoleDashboardData,
+} from './demo-dashboard-data';
+export { createAgentConsoleDemoHandlers } from './demo-runtime';
+export {
+	AGENT_CONSOLE_DEMO_ORGANIZATION_ID,
+	AGENT_CONSOLE_DEMO_PROJECT_ID,
+} from './demo-runtime-seed';
 export { MOCK_AGENTS } from './mock-agents';
 export { MOCK_RUNS } from './mock-runs';
 export { MOCK_TOOLS } from './mock-tools';

package/src/shared/mock-runs.ts

@@ -5,6 +5,7 @@ export const MOCK_RUNS = [
 	{
 		id: 'run-1',
 		organizationId: 'demo-org',
+		projectId: 'demo-project',
 		agentId: 'agent-1',
 		agentName: 'Customer Support Bot',
 		userId: 'user-1',
@@ -27,6 +28,7 @@ export const MOCK_RUNS = [
 	{
 		id: 'run-2',
 		organizationId: 'demo-org',
+		projectId: 'demo-project',
 		agentId: 'agent-2',
 		agentName: 'Code Review Assistant',
 		userId: 'user-2',
@@ -44,6 +46,7 @@ export const MOCK_RUNS = [
 	{
 		id: 'run-3',
 		organizationId: 'demo-org',
+		projectId: 'demo-project',
 		agentId: 'agent-1',
 		agentName: 'Customer Support Bot',
 		userId: 'user-1',
@@ -65,6 +68,7 @@ export const MOCK_RUNS = [
 	{
 		id: 'run-4',
 		organizationId: 'demo-org',
+		projectId: 'demo-project',
 		agentId: 'agent-3',
 		agentName: 'Data Analyst',
 		userId: 'user-3',
@@ -86,6 +90,7 @@ export const MOCK_RUNS = [
 	{
 		id: 'run-5',
 		organizationId: 'demo-org',
+		projectId: 'demo-project',
 		agentId: 'agent-2',
 		agentName: 'Code Review Assistant',
 		userId: 'user-2',

package/src/tool/tool.handler.ts

@@ -1,7 +1,26 @@
 /**
  * Mock handlers for Tool contracts.
  */
+
 import { MOCK_TOOLS } from '../shared/mock-tools';
+import {
+	CreateToolCommand,
+	GetToolQuery,
+	ListToolsQuery,
+	TestToolCommand,
+	UpdateToolCommand,
+} from './tool.operation';
+
+const TOOL_HANDLER_CONTRACTS = [
+	CreateToolCommand,
+	GetToolQuery,
+	ListToolsQuery,
+	TestToolCommand,
+	UpdateToolCommand,
+] as const;
+void TOOL_HANDLER_CONTRACTS;
+
+let nextMockToolId = MOCK_TOOLS.length + 1;
 
 export interface ListToolsInput {
 	organizationId: string;
@@ -107,7 +126,7 @@ export async function mockCreateToolHandler(input: {
 	);
 	if (exists) throw new Error('SLUG_EXISTS');
 	return {
-		id: `tool-${Date.now()}`,
+		id: `tool-${nextMockToolId++}`,
 		name: input.name,
 		slug: input.slug,
 		status: 'DRAFT' as const,
@@ -142,13 +161,11 @@ export async function mockTestToolHandler(input: {
 	const tool = MOCK_TOOLS.find((t) => t.id === input.toolId);
 	if (!tool) throw new Error('TOOL_NOT_FOUND');
 
-	// Simulate tool execution
-	const startTime = Date.now();
 	await new Promise((resolve) => setTimeout(resolve, 100));
 
 	return {
 		success: true,
 		output: { result: 'Test successful', input: input.testInput },
-		durationMs: Date.now() - startTime,
+		durationMs: 100,
 	};
 }