@contractspec/example.agent-console 3.7.7 → 3.8.4

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,
+	};
+}

package/src/run/run.handler.ts

@@ -4,6 +4,22 @@
 
 import { MOCK_AGENTS } from '../shared/mock-agents';
 import { MOCK_RUNS } from '../shared/mock-runs';
+import {
+	CancelRunCommand,
+	ExecuteAgentCommand,
+	GetRunQuery,
+	ListRunsQuery,
+} from './run.operation';
+
+const RUN_HANDLER_CONTRACTS = [
+	CancelRunCommand,
+	ExecuteAgentCommand,
+	GetRunQuery,
+	ListRunsQuery,
+] as const;
+void RUN_HANDLER_CONTRACTS;
+
+let nextMockRunId = MOCK_RUNS.length + 1;
 
 export interface ListRunsInput {
 	organizationId?: string;
@@ -117,7 +133,7 @@ export async function mockExecuteAgentHandler(input: {
 	if (agent.status !== 'ACTIVE') throw new Error('AGENT_NOT_ACTIVE');
 
 	return {
-		runId: `run-${Date.now()}`,
+		runId: `run-${nextMockRunId++}`,
 		status: 'QUEUED' as const,
 		estimatedWaitMs: 500,
 	};

package/src/shared/demo-dashboard-data.ts

@@ -0,0 +1,58 @@
+import type { AgentHandlers } from '../handlers/agent.handlers';
+import { createAgentConsoleDemoHandlers } from './demo-runtime';
+import {
+	AGENT_CONSOLE_DEMO_ORGANIZATION_ID,
+	AGENT_CONSOLE_DEMO_PROJECT_ID,
+} from './demo-runtime-seed';
+
+export interface AgentConsoleDashboardData {
+	agents: Awaited<ReturnType<AgentHandlers['listAgents']>>['items'];
+	runs: Awaited<ReturnType<AgentHandlers['listRuns']>>['items'];
+	tools: Awaited<ReturnType<AgentHandlers['listTools']>>['items'];
+	summary: {
+		totalAgents: number;
+		totalRuns: number;
+		totalTools: number;
+	};
+}
+
+export async function getAgentConsoleDashboardData(
+	handlers: AgentHandlers,
+	params: { projectId: string; organizationId?: string }
+): Promise<AgentConsoleDashboardData> {
+	const organizationId =
+		params.organizationId ?? AGENT_CONSOLE_DEMO_ORGANIZATION_ID;
+	const [agentsResult, runsResult, toolsResult] = await Promise.all([
+		handlers.listAgents({
+			projectId: params.projectId,
+			organizationId,
+			limit: 10,
+		}),
+		handlers.listRuns({ projectId: params.projectId, limit: 10 }),
+		handlers.listTools({
+			projectId: params.projectId,
+			organizationId,
+			limit: 10,
+		}),
+	]);
+
+	return {
+		agents: agentsResult.items,
+		runs: runsResult.items,
+		tools: toolsResult.items,
+		summary: {
+			totalAgents: agentsResult.total,
+			totalRuns: runsResult.total,
+			totalTools: toolsResult.total,
+		},
+	};
+}
+
+export async function getFallbackAgentConsoleDashboardData() {
+	const handlers = createAgentConsoleDemoHandlers({
+		projectId: AGENT_CONSOLE_DEMO_PROJECT_ID,
+	});
+	return getAgentConsoleDashboardData(handlers, {
+		projectId: AGENT_CONSOLE_DEMO_PROJECT_ID,
+	});
+}