@contractspec/example.agent-console 3.7.6 → 3.8.2

package/src/handlers/index.ts

@@ -1,30 +1,46 @@
 /**
  * Agent Console Handlers - re-exports from domain modules for backward compatibility.
  */
+import {
+	CreateAgentCommand,
+	ListAgentsQuery,
+	UpdateAgentCommand,
+} from '../agent/agent.operation';
+import { ExecuteAgentCommand, ListRunsQuery } from '../run/run.operation';
+import { ListToolsQuery } from '../tool/tool.operation';
+
+const HANDLER_BARREL_CONTRACTS = [
+	CreateAgentCommand,
+	ListAgentsQuery,
+	UpdateAgentCommand,
+	ExecuteAgentCommand,
+	ListRunsQuery,
+	ListToolsQuery,
+] as const;
+void HANDLER_BARREL_CONTRACTS;
 
 // Agent handlers and types
 export {
-  mockCreateAgentHandler,
-  mockGetAgentHandler,
-  mockListAgentsHandler,
-  type AgentSummary,
+	type AgentSummary,
+	mockCreateAgentHandler,
+	mockGetAgentHandler,
+	mockListAgentsHandler,
 } from '../agent/agent.handler';
 
 // Run handlers and types
 export {
-  mockExecuteAgentHandler,
-  mockGetRunHandler,
-  mockListRunsHandler,
-  type RunSummary,
+	mockExecuteAgentHandler,
+	mockGetRunHandler,
+	mockListRunsHandler,
+	type RunSummary,
 } from '../run/run.handler';
-
+export { createAgentConsoleDemoHandlers } from '../shared/demo-runtime';
 // Tool handlers and types
 export {
-  mockCreateToolHandler,
-  mockGetToolHandler,
-  mockListToolsHandler,
-  type ToolSummary,
+	mockCreateToolHandler,
+	mockGetToolHandler,
+	mockListToolsHandler,
+	type ToolSummary,
 } from '../tool/tool.handler';
-
 // Runtime handlers (PGLite)
 export * from './agent.handlers';

package/src/handlers/mock-handlers.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, it } from 'bun:test';
+import { mockCreateAgentHandler } from '../agent/agent.handler';
+import { mockExecuteAgentHandler } from '../run/run.handler';
+import {
+	mockCreateToolHandler,
+	mockTestToolHandler,
+} from '../tool/tool.handler';
+
+function numericSuffix(value: string): number {
+	const suffix = value.split('-').at(-1);
+	if (!suffix) {
+		throw new Error(`Missing numeric suffix in ${value}.`);
+	}
+	return Number.parseInt(suffix, 10);
+}
+
+describe('agent-console mock handlers', () => {
+	it('allocates monotonic mock agent and tool ids', async () => {
+		const createdAgentA = await mockCreateAgentHandler({
+			organizationId: 'demo-org',
+			name: 'Meetup Mock Agent A',
+			slug: 'meetup-mock-agent-a',
+			modelProvider: 'OPENAI',
+			modelName: 'gpt-5.4',
+			systemPrompt: 'Keep responses stable.',
+		});
+		const createdAgentB = await mockCreateAgentHandler({
+			organizationId: 'demo-org',
+			name: 'Meetup Mock Agent B',
+			slug: 'meetup-mock-agent-b',
+			modelProvider: 'OPENAI',
+			modelName: 'gpt-5.4',
+			systemPrompt: 'Keep responses stable.',
+		});
+		const createdToolA = await mockCreateToolHandler({
+			organizationId: 'demo-org',
+			name: 'Meetup Tool A',
+			slug: 'meetup-tool-a',
+			description: 'First deterministic tool.',
+			implementationType: 'function',
+		});
+		const createdToolB = await mockCreateToolHandler({
+			organizationId: 'demo-org',
+			name: 'Meetup Tool B',
+			slug: 'meetup-tool-b',
+			description: 'Second deterministic tool.',
+			implementationType: 'function',
+		});
+
+		expect(numericSuffix(createdAgentB.id)).toBe(
+			numericSuffix(createdAgentA.id) + 1
+		);
+		expect(numericSuffix(createdToolB.id)).toBe(
+			numericSuffix(createdToolA.id) + 1
+		);
+	});
+
+	it('allocates monotonic run ids and returns a stable tool test duration', async () => {
+		const firstRun = await mockExecuteAgentHandler({
+			agentId: 'agent-1',
+			input: { message: 'First run' },
+		});
+		const secondRun = await mockExecuteAgentHandler({
+			agentId: 'agent-1',
+			input: { message: 'Second run' },
+		});
+		const toolResult = await mockTestToolHandler({
+			toolId: 'tool-1',
+			testInput: { query: 'stable duration' },
+		});
+
+		expect(numericSuffix(secondRun.runId)).toBe(
+			numericSuffix(firstRun.runId) + 1
+		);
+		expect(toolResult.durationMs).toBe(100);
+	});
+});

package/src/index.ts

@@ -17,16 +17,17 @@
 
 // Domain exports
 export * from './agent';
-export * from './run';
-export * from './tool';
-export * from './shared';
-export * from './ui';
-export {
-  createAgentHandlers,
-  type AgentHandlers,
-} from './handlers/agent.handlers';
-
 // Feature spec export
 export * from './agent.feature';
 export { default as example } from './example';
+export {
+	type AgentHandlers,
+	createAgentHandlers,
+} from './handlers/agent.handlers';
+export * from './proof';
+export * from './run';
+export * from './shared';
+export * from './tool';
+export * from './ui';
+export * from './visualizations';
 import './docs';

package/src/presentations/index.ts

@@ -4,23 +4,21 @@
 
 // Agent presentations
 export {
-  AgentListPresentation,
-  AgentDetailPresentation,
-  AgentConsoleDashboardPresentation,
+	AgentConsoleDashboardPresentation,
+	AgentDetailPresentation,
+	AgentListPresentation,
 } from '../agent/agent.presentation';
-
 // Run presentations
+// Alias: RunMetricsPresentation -> RunDetailPresentation (for backward compatibility)
 export {
-  RunListPresentation,
-  RunDetailPresentation,
+	RunDetailPresentation,
+	RunDetailPresentation as RunMetricsPresentation,
+	RunListPresentation,
 } from '../run/run.presentation';
-// Alias: RunMetricsPresentation -> RunDetailPresentation (for backward compatibility)
-export { RunDetailPresentation as RunMetricsPresentation } from '../run/run.presentation';
-
 // Tool presentations
+// Alias: ToolRegistryPresentation -> ToolListPresentation (for backward compatibility)
 export {
-  ToolListPresentation,
-  ToolDetailPresentation,
+	ToolDetailPresentation,
+	ToolListPresentation,
+	ToolListPresentation as ToolRegistryPresentation,
 } from '../tool/tool.presentation';
-// Alias: ToolRegistryPresentation -> ToolListPresentation (for backward compatibility)
-export { ToolListPresentation as ToolRegistryPresentation } from '../tool/tool.presentation';

package/src/proof/index.ts

@@ -0,0 +1,2 @@
+export * from './meetup-proof.scenario';
+export * from './meetup-proof.suite';

package/src/proof/meetup-proof.runtime.ts

@@ -0,0 +1,196 @@
+import type {
+	HarnessArtifactQuery,
+	HarnessArtifactStore,
+	HarnessExecutionAdapter,
+	HarnessStoredArtifact,
+} from '@contractspec/lib.harness';
+import type { AgentHandlers, Run } from '../handlers/agent.handlers';
+import { getAgentConsoleDashboardData } from '../shared/demo-dashboard-data';
+import { MEETUP_AGENT_NAME } from './meetup-proof.scenario';
+
+export class MemoryArtifactStore implements HarnessArtifactStore {
+	private readonly items: HarnessStoredArtifact[] = [];
+
+	async put(artifact: HarnessStoredArtifact) {
+		this.items.push(artifact);
+		return artifact;
+	}
+
+	async get(artifactId: string) {
+		return this.items.find((artifact) => artifact.artifactId === artifactId);
+	}
+
+	async list(query: HarnessArtifactQuery = {}) {
+		return this.items.filter((artifact) => {
+			if (query.runId && artifact.runId !== query.runId) return false;
+			if (query.stepId && artifact.stepId !== query.stepId) return false;
+			if (query.kind && artifact.kind !== query.kind) return false;
+			return true;
+		});
+	}
+}
+
+export function createProofNow() {
+	let tick = 0;
+	const base = Date.parse('2026-03-20T09:30:00.000Z');
+	return () => new Date(base + tick++ * 60_000);
+}
+
+export function createProofIdFactory(prefix: string) {
+	let index = 0;
+	return () => `${prefix}-${++index}`;
+}
+
+export function createMeetupEntityIdFactory() {
+	const counters = { agent: 0, run: 0 };
+	return (kind: 'agent' | 'run') => `${kind}-meetup-${++counters[kind]}`;
+}
+
+interface MeetupExecutionState {
+	agentId: string;
+	runId: string;
+}
+
+function buildRunSummary(run: Run) {
+	return {
+		status: 'completed' as const,
+		summary: `Executed ${run.agentName} and completed ${run.id}.`,
+		output: {
+			runId: run.id,
+			status: run.status,
+			totalTokens: run.totalTokens,
+		},
+		artifacts: [
+			{
+				kind: 'step-summary' as const,
+				summary: `Completed ${run.id} for ${run.agentName}`,
+			},
+		],
+	};
+}
+
+export function createMeetupProofAdapter(input: {
+	handlers: AgentHandlers;
+	projectId: string;
+	organizationId: string;
+	state: MeetupExecutionState;
+}): HarnessExecutionAdapter {
+	return {
+		mode: 'code-execution',
+		supports: () => true,
+		execute: async ({ step }) => {
+			const { handlers, projectId, organizationId, state } = input;
+			switch (step.key) {
+				case 'open-dashboard': {
+					const dashboard = await getAgentConsoleDashboardData(handlers, {
+						projectId,
+						organizationId,
+					});
+					return {
+						status: 'completed',
+						summary: `Seeded dashboard ready with ${dashboard.summary.totalAgents} agents, ${dashboard.summary.totalTools} tools, and ${dashboard.summary.totalRuns} runs.`,
+						output: {
+							agentCount: dashboard.summary.totalAgents,
+							runCount: dashboard.summary.totalRuns,
+							toolCount: dashboard.summary.totalTools,
+						},
+						artifacts: [
+							{
+								kind: 'step-summary',
+								summary: `Seeded dashboard agents=${dashboard.summary.totalAgents} tools=${dashboard.summary.totalTools} runs=${dashboard.summary.totalRuns}`,
+							},
+						],
+					};
+				}
+				case 'create-agent': {
+					const agent = await handlers.createAgent(
+						{
+							name: MEETUP_AGENT_NAME,
+							description:
+								'Offline-safe walkthrough agent for the Paris meetup.',
+							systemPrompt:
+								'Demonstrate the deterministic ContractSpec meetup flow.',
+						},
+						{ projectId, organizationId }
+					);
+					state.agentId = agent.id;
+					return {
+						status: 'completed',
+						summary: `Created ${agent.name} as ${agent.id}.`,
+						output: {
+							agentId: agent.id,
+							status: agent.status,
+						},
+						artifacts: [
+							{
+								kind: 'step-summary',
+								summary: `Created ${agent.name} (${agent.id})`,
+							},
+						],
+					};
+				}
+				case 'activate-agent': {
+					const agent = await handlers.updateAgent({
+						id: state.agentId,
+						status: 'ACTIVE',
+					});
+					return {
+						status: 'completed',
+						summary: `Activated ${agent.name}.`,
+						output: {
+							agentId: agent.id,
+							status: agent.status,
+						},
+						artifacts: [
+							{
+								kind: 'step-summary',
+								summary: `Activated ${agent.name}`,
+							},
+						],
+					};
+				}
+				case 'execute-agent': {
+					const run = await handlers.executeAgent({
+						agentId: state.agentId,
+						message: 'Summarize the meetup proof lane.',
+						context: { projectId, organizationId },
+					});
+					state.runId = run.id;
+					return buildRunSummary(run);
+				}
+				case 'inspect-dashboard': {
+					const [dashboard, metrics] = await Promise.all([
+						getAgentConsoleDashboardData(handlers, {
+							projectId,
+							organizationId,
+						}),
+						handlers.getRunMetrics({ projectId }),
+					]);
+					return {
+						status: 'completed',
+						summary: `${MEETUP_AGENT_NAME} is visible with ${dashboard.summary.totalAgents} agents and ${dashboard.summary.totalRuns} runs.`,
+						output: {
+							agentCount: dashboard.summary.totalAgents,
+							runCount: dashboard.summary.totalRuns,
+							toolCount: dashboard.summary.totalTools,
+							latestAgentName: dashboard.agents[0]?.name ?? null,
+							latestRunId: dashboard.runs[0]?.id ?? null,
+							successRate: metrics.successRate,
+						},
+						artifacts: [
+							{
+								kind: 'step-summary',
+								summary: `Final dashboard agents=${dashboard.summary.totalAgents} runs=${dashboard.summary.totalRuns}`,
+							},
+						],
+					};
+				}
+				default:
+					return {
+						status: 'failed',
+						summary: `Unknown meetup proof step ${step.key}.`,
+					};
+			}
+		},
+	};
+}

package/src/proof/meetup-proof.scenario.ts

@@ -0,0 +1,99 @@
+import { defineHarnessScenario } from '@contractspec/lib.contracts-spec';
+import { MOCK_AGENTS } from '../shared/mock-agents';
+import { MOCK_RUNS } from '../shared/mock-runs';
+import { MOCK_TOOLS } from '../shared/mock-tools';
+
+export const MEETUP_AGENT_NAME = 'Paris Meetup Demo Agent';
+const SEEDED_COMPLETED_RUNS = MOCK_RUNS.filter(
+	(run) => run.status === 'COMPLETED'
+).length;
+const SUCCESS_RATE_AFTER_MEETUP_EXECUTION =
+	(SEEDED_COMPLETED_RUNS + 1) / (MOCK_RUNS.length + 1);
+
+export const AGENT_CONSOLE_MEETUP_PROOF_SCENARIO = defineHarnessScenario({
+	meta: {
+		key: 'agent-console.meetup.proof',
+		version: '1.0.0',
+		title: 'Agent console meetup proof',
+		description:
+			'Verifies the deterministic autonomous-agent walkthrough end-to-end.',
+		domain: 'agent-console',
+		owners: ['@agent-console-team'],
+		tags: ['meetup', 'proof', 'autonomous-agents'],
+		stability: 'experimental',
+	},
+	target: {
+		allowlistedDomains: ['sandbox.contractspec.local'],
+		isolation: 'sandbox',
+	},
+	allowedModes: ['code-execution'],
+	steps: [
+		{
+			key: 'open-dashboard',
+			description: 'Inspect seeded dashboard state',
+			actionClass: 'code-exec-read',
+			intent:
+				'Confirm the local demo starts with seeded agents, tools, and runs.',
+		},
+		{
+			key: 'create-agent',
+			description: 'Create the meetup demo agent',
+			actionClass: 'code-exec-mutate',
+			intent: 'Add a new agent for the walkthrough.',
+			mutatesState: true,
+		},
+		{
+			key: 'activate-agent',
+			description: 'Activate the meetup demo agent',
+			actionClass: 'code-exec-mutate',
+			intent: 'Move the new agent into an executable state.',
+			mutatesState: true,
+		},
+		{
+			key: 'execute-agent',
+			description: 'Run the meetup demo agent',
+			actionClass: 'code-exec-mutate',
+			intent: 'Create a deterministic completed run.',
+			mutatesState: true,
+		},
+		{
+			key: 'inspect-dashboard',
+			description: 'Confirm dashboard totals after execution',
+			actionClass: 'code-exec-read',
+			intent: 'Verify the new agent and run are visible in the demo state.',
+		},
+	],
+	assertions: [
+		{
+			key: 'captured-step-summaries',
+			type: 'count',
+			source: 'step-summary',
+			match: 5,
+		},
+		{
+			key: 'execution-completed',
+			type: 'step-status',
+			source: 'execute-agent',
+			match: 'completed',
+		},
+		{
+			key: 'final-summary-mentions-meetup-agent',
+			type: 'text-match',
+			source: 'inspect-dashboard',
+			match: MEETUP_AGENT_NAME,
+		},
+		{
+			key: 'final-dashboard-shape',
+			type: 'json-match',
+			source: 'inspect-dashboard',
+			match: {
+				agentCount: MOCK_AGENTS.length + 1,
+				runCount: MOCK_RUNS.length + 1,
+				toolCount: MOCK_TOOLS.length,
+				latestAgentName: MEETUP_AGENT_NAME,
+				latestRunId: 'run-meetup-1',
+				successRate: SUCCESS_RATE_AFTER_MEETUP_EXECUTION,
+			},
+		},
+	],
+});

package/src/proof/meetup-proof.suite.ts

@@ -0,0 +1,29 @@
+import { defineHarnessSuite } from '@contractspec/lib.contracts-spec';
+import { AGENT_CONSOLE_MEETUP_PROOF_SCENARIO } from './meetup-proof.scenario';
+
+export const AgentConsoleMeetupProofSuite = defineHarnessSuite({
+	meta: {
+		key: 'agent-console.meetup.proof-suite',
+		version: '1.0.0',
+		title: 'Agent console meetup proof suite',
+		description:
+			'Bundles the deterministic meetup walkthrough into a reusable harness suite.',
+		domain: 'agent-console',
+		owners: ['@agent-console-team'],
+		tags: ['meetup', 'proof', 'harness-suite'],
+		stability: 'experimental',
+	},
+	summary:
+		'Runs the canonical agent-console meetup scenario and validates the final dashboard evidence.',
+	tags: ['agent-console', 'meetup', 'proof'],
+	scenarios: [
+		{
+			scenario: {
+				key: AGENT_CONSOLE_MEETUP_PROOF_SCENARIO.meta.key,
+				version: AGENT_CONSOLE_MEETUP_PROOF_SCENARIO.meta.version,
+			},
+			required: true,
+			weight: 1,
+		},
+	],
+});

package/src/proof/meetup-proof.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'bun:test';
+import { summarizeHarnessReplayBundle } from '@contractspec/lib.harness';
+import { runAgentConsoleMeetupProof } from './meetup-proof';
+import { AGENT_CONSOLE_MEETUP_PROOF_SCENARIO } from './meetup-proof.scenario';
+
+describe('agent-console meetup proof', () => {
+	it('runs the canonical walkthrough and generates a replay bundle', async () => {
+		const result = await runAgentConsoleMeetupProof();
+		const summary = summarizeHarnessReplayBundle(result.replayBundle);
+
+		expect(result.evaluation.status).toBe('passed');
+		expect(
+			result.evaluation.assertions.every((item) => item.status === 'passed')
+		).toBe(true);
+		expect(result.evaluation.run.scenarioKey).toBe(
+			AGENT_CONSOLE_MEETUP_PROOF_SCENARIO.meta.key
+		);
+		expect(result.replayUri).toBe('memory://agent-console-meetup-proof');
+		expect(summary.status).toBe('completed');
+		expect(summary.stepCount).toBe(
+			AGENT_CONSOLE_MEETUP_PROOF_SCENARIO.steps.length
+		);
+		expect(summary.artifactCount).toBe(
+			AGENT_CONSOLE_MEETUP_PROOF_SCENARIO.steps.length
+		);
+		expect(summary.failedAssertions).toBe(0);
+	});
+});

package/src/proof/meetup-proof.ts

@@ -0,0 +1,130 @@
+import {
+	HarnessEvaluationRunner,
+	type HarnessReplayBundle,
+	type HarnessReplaySink,
+	HarnessRunner,
+} from '@contractspec/lib.harness';
+import { createAgentConsoleDemoHandlers } from '../shared/demo-runtime';
+import {
+	AGENT_CONSOLE_DEMO_ORGANIZATION_ID,
+	AGENT_CONSOLE_DEMO_PROJECT_ID,
+} from '../shared/demo-runtime-seed';
+import {
+	createMeetupEntityIdFactory,
+	createMeetupProofAdapter,
+	createProofIdFactory,
+	createProofNow,
+	MemoryArtifactStore,
+} from './meetup-proof.runtime';
+import { AGENT_CONSOLE_MEETUP_PROOF_SCENARIO } from './meetup-proof.scenario';
+
+function isHarnessReplayBundle(value: unknown): value is HarnessReplayBundle {
+	return (
+		typeof value === 'object' &&
+		value !== null &&
+		'version' in value &&
+		'run' in value &&
+		'assertions' in value &&
+		'artifacts' in value
+	);
+}
+
+export async function runAgentConsoleMeetupProof(input?: {
+	projectId?: string;
+	organizationId?: string;
+	replaySink?: HarnessReplaySink;
+}) {
+	const projectId = input?.projectId ?? AGENT_CONSOLE_DEMO_PROJECT_ID;
+	const organizationId =
+		input?.organizationId ?? AGENT_CONSOLE_DEMO_ORGANIZATION_ID;
+	const harnessNow = createProofNow();
+	const handlers = createAgentConsoleDemoHandlers({
+		projectId,
+		organizationId,
+		now: createProofNow(),
+		idFactory: createMeetupEntityIdFactory(),
+	});
+	const executionState = {
+		agentId: '',
+		runId: '',
+	};
+	const artifactStore = new MemoryArtifactStore();
+	const replayUris: string[] = [];
+	let replayBundle: HarnessReplayBundle | null = null;
+	const adapter = createMeetupProofAdapter({
+		handlers,
+		projectId,
+		organizationId,
+		state: executionState,
+	});
+
+	const replaySink: HarnessReplaySink = {
+		async save(bundle: unknown) {
+			if (!isHarnessReplayBundle(bundle)) {
+				throw new Error('Replay sink received an invalid harness bundle.');
+			}
+			replayBundle = bundle;
+			const delegatedUri = await input?.replaySink?.save(bundle);
+			const uri = delegatedUri ?? 'memory://agent-console-meetup-proof';
+			replayUris.push(uri);
+			return uri;
+		},
+	};
+
+	const runner = new HarnessRunner({
+		targetResolver: {
+			async resolve() {
+				return {
+					targetId: 'sandbox-agent-console',
+					kind: 'sandbox',
+					isolation: 'sandbox',
+					environment: 'local',
+					baseUrl: 'https://sandbox.contractspec.local/agent-console',
+					allowlistedDomains: ['sandbox.contractspec.local'],
+				};
+			},
+		},
+		artifactStore,
+		adapters: [adapter],
+		approvalGateway: {
+			async approve() {
+				return { approved: true, approverId: 'meetup-proof' };
+			},
+		},
+		now: harnessNow,
+		idFactory: createProofIdFactory('proof'),
+		defaultMode: 'code-execution',
+	});
+	const evaluationRunner = new HarnessEvaluationRunner({
+		runner,
+		replaySink,
+		now: harnessNow,
+		idFactory: createProofIdFactory('evaluation'),
+	});
+	const evaluation = await evaluationRunner.runScenarioEvaluation({
+		scenario: AGENT_CONSOLE_MEETUP_PROOF_SCENARIO,
+		mode: 'code-execution',
+		target: {
+			targetId: 'sandbox-agent-console',
+			isolation: 'sandbox',
+			baseUrl: 'https://sandbox.contractspec.local/agent-console',
+			allowlistedDomains: ['sandbox.contractspec.local'],
+		},
+		context: {
+			metadata: {
+				lane: 'meetup-proof',
+				templateId: 'agent-console',
+			},
+		},
+	});
+
+	if (!replayBundle) {
+		throw new Error('Meetup proof did not produce a replay bundle.');
+	}
+
+	return {
+		evaluation,
+		replayBundle,
+		replayUri: replayUris[0] ?? evaluation.replayBundleUri,
+	};
+}