@contractspec/example.agent-console 3.7.7 → 3.8.4

package/proofs/agent-console-meetup.replay.json

@@ -0,0 +1,220 @@
+{
+	"version": "1",
+	"createdAt": "2026-03-20T09:48:00.000Z",
+	"run": {
+		"runId": "proof-1",
+		"status": "completed",
+		"mode": "code-execution",
+		"scenarioKey": "agent-console.meetup.proof",
+		"target": {
+			"targetId": "sandbox-agent-console",
+			"kind": "sandbox",
+			"isolation": "sandbox",
+			"environment": "local",
+			"baseUrl": "https://sandbox.contractspec.local/agent-console",
+			"allowlistedDomains": ["sandbox.contractspec.local"]
+		},
+		"steps": [
+			{
+				"stepId": "proof-2",
+				"stepKey": "open-dashboard",
+				"runId": "proof-1",
+				"mode": "code-execution",
+				"actionClass": "code-exec-read",
+				"verdict": "autonomous",
+				"requiresApproval": false,
+				"status": "completed",
+				"startedAt": "2026-03-20T09:32:00.000Z",
+				"output": {
+					"agentCount": 4,
+					"runCount": 5,
+					"toolCount": 5
+				},
+				"completedAt": "2026-03-20T09:34:00.000Z",
+				"summary": "Seeded dashboard ready with 4 agents, 5 tools, and 5 runs.",
+				"metadata": {
+					"output": {
+						"agentCount": 4,
+						"runCount": 5,
+						"toolCount": 5
+					}
+				}
+			},
+			{
+				"stepId": "proof-4",
+				"stepKey": "create-agent",
+				"runId": "proof-1",
+				"mode": "code-execution",
+				"actionClass": "code-exec-mutate",
+				"verdict": "assist",
+				"requiresApproval": true,
+				"status": "completed",
+				"startedAt": "2026-03-20T09:35:00.000Z",
+				"output": {
+					"agentId": "agent-meetup-1",
+					"status": "DRAFT"
+				},
+				"completedAt": "2026-03-20T09:37:00.000Z",
+				"summary": "Created Paris Meetup Demo Agent as agent-meetup-1.",
+				"metadata": {
+					"output": {
+						"agentId": "agent-meetup-1",
+						"status": "DRAFT"
+					}
+				}
+			},
+			{
+				"stepId": "proof-6",
+				"stepKey": "activate-agent",
+				"runId": "proof-1",
+				"mode": "code-execution",
+				"actionClass": "code-exec-mutate",
+				"verdict": "assist",
+				"requiresApproval": true,
+				"status": "completed",
+				"startedAt": "2026-03-20T09:38:00.000Z",
+				"output": {
+					"agentId": "agent-meetup-1",
+					"status": "ACTIVE"
+				},
+				"completedAt": "2026-03-20T09:40:00.000Z",
+				"summary": "Activated Paris Meetup Demo Agent.",
+				"metadata": {
+					"output": {
+						"agentId": "agent-meetup-1",
+						"status": "ACTIVE"
+					}
+				}
+			},
+			{
+				"stepId": "proof-8",
+				"stepKey": "execute-agent",
+				"runId": "proof-1",
+				"mode": "code-execution",
+				"actionClass": "code-exec-mutate",
+				"verdict": "assist",
+				"requiresApproval": true,
+				"status": "completed",
+				"startedAt": "2026-03-20T09:41:00.000Z",
+				"output": {
+					"runId": "run-meetup-1",
+					"status": "COMPLETED",
+					"totalTokens": 1028
+				},
+				"completedAt": "2026-03-20T09:43:00.000Z",
+				"summary": "Executed Paris Meetup Demo Agent and completed run-meetup-1.",
+				"metadata": {
+					"output": {
+						"runId": "run-meetup-1",
+						"status": "COMPLETED",
+						"totalTokens": 1028
+					}
+				}
+			},
+			{
+				"stepId": "proof-10",
+				"stepKey": "inspect-dashboard",
+				"runId": "proof-1",
+				"mode": "code-execution",
+				"actionClass": "code-exec-read",
+				"verdict": "autonomous",
+				"requiresApproval": false,
+				"status": "completed",
+				"startedAt": "2026-03-20T09:44:00.000Z",
+				"output": {
+					"agentCount": 5,
+					"runCount": 6,
+					"toolCount": 5,
+					"latestAgentName": "Paris Meetup Demo Agent",
+					"latestRunId": "run-meetup-1",
+					"successRate": 0.6666666666666666
+				},
+				"completedAt": "2026-03-20T09:46:00.000Z",
+				"summary": "Paris Meetup Demo Agent is visible with 5 agents and 6 runs.",
+				"metadata": {
+					"output": {
+						"agentCount": 5,
+						"runCount": 6,
+						"toolCount": 5,
+						"latestAgentName": "Paris Meetup Demo Agent",
+						"latestRunId": "run-meetup-1",
+						"successRate": 0.6666666666666666
+					}
+				}
+			}
+		],
+		"createdAt": "2026-03-20T09:30:00.000Z",
+		"updatedAt": "2026-03-20T09:47:00.000Z",
+		"evidenceCount": 5
+	},
+	"assertions": [
+		{
+			"assertionKey": "captured-step-summaries",
+			"status": "passed"
+		},
+		{
+			"assertionKey": "execution-completed",
+			"status": "passed"
+		},
+		{
+			"assertionKey": "final-summary-mentions-meetup-agent",
+			"status": "passed"
+		},
+		{
+			"assertionKey": "final-dashboard-shape",
+			"status": "passed"
+		}
+	],
+	"artifacts": [
+		{
+			"artifactId": "proof-3",
+			"kind": "step-summary",
+			"runId": "proof-1",
+			"stepId": "proof-2",
+			"uri": "artifact://proof-3",
+			"hash": "815b21629e7e8a82376bd9c47e49192f9c4d5ff3b81bfd23d149b2922834b802",
+			"summary": "Seeded dashboard agents=4 tools=5 runs=5",
+			"createdAt": "2026-03-20T09:33:00.000Z"
+		},
+		{
+			"artifactId": "proof-5",
+			"kind": "step-summary",
+			"runId": "proof-1",
+			"stepId": "proof-4",
+			"uri": "artifact://proof-5",
+			"hash": "6deb2379988765661f26baaddaf5d3dd8d6115097c3f318f257b2f0fd71b8041",
+			"summary": "Created Paris Meetup Demo Agent (agent-meetup-1)",
+			"createdAt": "2026-03-20T09:36:00.000Z"
+		},
+		{
+			"artifactId": "proof-7",
+			"kind": "step-summary",
+			"runId": "proof-1",
+			"stepId": "proof-6",
+			"uri": "artifact://proof-7",
+			"hash": "eedef831df5bd02593572bcd979efbf9155d3aef4b6bba3bb4b5444ba6f59f6a",
+			"summary": "Activated Paris Meetup Demo Agent",
+			"createdAt": "2026-03-20T09:39:00.000Z"
+		},
+		{
+			"artifactId": "proof-9",
+			"kind": "step-summary",
+			"runId": "proof-1",
+			"stepId": "proof-8",
+			"uri": "artifact://proof-9",
+			"hash": "6939940cd8a2219f6387ea2fb1341b33aee5ab2c2b11f6e4755f157c37afa572",
+			"summary": "Completed run-meetup-1 for Paris Meetup Demo Agent",
+			"createdAt": "2026-03-20T09:42:00.000Z"
+		},
+		{
+			"artifactId": "proof-11",
+			"kind": "step-summary",
+			"runId": "proof-1",
+			"stepId": "proof-10",
+			"uri": "artifact://proof-11",
+			"hash": "d62d67ef87eb4dc831ab2bb7cd4ab30bd02b88e832c22f338d89ecdfe425db06",
+			"summary": "Final dashboard agents=5 runs=6",
+			"createdAt": "2026-03-20T09:45:00.000Z"
+		}
+	]
+}

package/src/agent/agent.handler.ts

@@ -1,8 +1,25 @@
 /**
  * Mock handlers for Agent contracts.
  */
+
 import { MOCK_AGENTS } from '../shared/mock-agents';
 import { MOCK_TOOLS } from '../shared/mock-tools';
+import {
+	CreateAgentCommand,
+	GetAgentQuery,
+	ListAgentsQuery,
+	UpdateAgentCommand,
+} from './agent.operation';
+
+const AGENT_HANDLER_CONTRACTS = [
+	CreateAgentCommand,
+	GetAgentQuery,
+	ListAgentsQuery,
+	UpdateAgentCommand,
+] as const;
+void AGENT_HANDLER_CONTRACTS;
+
+let nextMockAgentId = MOCK_AGENTS.length + 1;
 
 export interface ListAgentsInput {
 	organizationId: string;
@@ -152,7 +169,7 @@ export async function mockCreateAgentHandler(input: {
 	);
 	if (exists) throw new Error('SLUG_EXISTS');
 	return {
-		id: `agent-${Date.now()}`,
+		id: `agent-${nextMockAgentId++}`,
 		name: input.name,
 		slug: input.slug,
 		status: 'DRAFT' as const,

package/src/agent.feature.ts

@@ -5,6 +5,7 @@
  */
 import type { FeatureModuleSpec } from '@contractspec/lib.contracts-spec';
 import { defineFeature } from '@contractspec/lib.contracts-spec';
+import { AgentVisualizationRefs } from './visualizations';
 
 /**
  * Agent Console feature module that bundles all agent, tool, and run
@@ -135,6 +136,8 @@ export const AgentConsoleFeature: FeatureModuleSpec = defineFeature({
 		},
 	],
 
+	visualizations: AgentVisualizationRefs,
+
 	// Capability requirements
 	capabilities: {
 		requires: [

package/src/docs/agent-console.docblock.ts

@@ -30,19 +30,21 @@ const agentConsoleDocBlocks: DocBlock[] = [
 		visibility: 'public',
 		route: '/docs/examples/agent-console/usage',
 		tags: ['ai', 'agents', 'usage'],
-		body: `## Setup
-1) Seed (if available) or create tools and agents; define run configs.
-2) Configure Notifications for run completion/failure; Audit for changes.
+		body: `## Canonical walkthrough
+1) Open the default sandbox route at \`/sandbox\` or \`/sandbox?template=agent-console\`.
+2) Inspect seeded agents, tools, runs, and metrics from the deterministic demo runtime.
+3) Create an agent, activate it, execute a run, and confirm the metrics update.
+4) Generate or inspect the replay proof at \`packages/examples/agent-console/proofs/agent-console-meetup.replay.json\`.
 
 ## Extend & regenerate
-1) Adjust tool schemas (inputs/outputs), agent configs, run metrics in spec.
+1) Adjust tool schemas (inputs/outputs), agent configs, and run metrics in spec.
 2) Regenerate to sync UI/API/events/logs; mark PII paths for run payloads.
-3) Use Feature Flags to gate risky tools or execution policies.
+3) Keep the demo runtime deterministic unless you are explicitly validating live providers.
 
 ## Guardrails
 - Emit events for run lifecycle; store logs with redaction where needed.
 - Enforce tool input validation; avoid unsafe arbitrary code exec in handlers.
-- Keep tenant/user scoping explicit for ops data.`,
+- Keep tenant/user scoping explicit for ops data and keep meetup demos offline-safe by default.`,
 	},
 	{
 		id: 'docs.examples.agent-console.reference',
@@ -63,11 +65,12 @@ const agentConsoleDocBlocks: DocBlock[] = [
 - tool.created, agent.created, run.started/completed/failed, tool.invoked.
 
 ## Presentations
-- Tool registry, agent list/detail, run list/detail, metrics dashboards.
+- Tool registry, agent list/detail, run list/detail, metrics dashboards, and a server-mode shared table for run history.
 
 ## Notes
 - Keep tool schemas explicit; enforce validation in spec.
-- Use Audit Trail for agent/run changes; Notifications for run outcomes.`,
+- Use the seeded demo runtime for sandbox and markdown walkthroughs.
+- Generate a replay bundle before demos or talks so the walkthrough has proof output ready.`,
 	},
 	{
 		id: 'docs.examples.agent-console.constraints',

package/src/example.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, test } from 'bun:test';
+import { AgentConsoleFeature } from './agent.feature';
+import example from './example';
+import {
+	AGENT_CONSOLE_MEETUP_PROOF_SCENARIO,
+	AgentConsoleMeetupProofSuite,
+} from './proof';
+import {
+	AGENT_CONSOLE_DEMO_ORGANIZATION_ID,
+	AGENT_CONSOLE_DEMO_PROJECT_ID,
+	createAgentConsoleDemoHandlers,
+} from './shared';
+
+describe('@contractspec/example.agent-console', () => {
+	test('publishes meetup-ready example metadata', () => {
+		expect(example.meta.key).toBe('agent-console');
+		expect(example.entrypoints.packageName).toBe(
+			'@contractspec/example.agent-console'
+		);
+		expect(example.surfaces.templates).toBe(true);
+		expect(example.surfaces.sandbox?.enabled).toBe(true);
+		expect(AgentConsoleFeature.meta.key).toBe(example.meta.key);
+	});
+
+	test('exports the canonical harness scenario and suite', () => {
+		expect(AGENT_CONSOLE_MEETUP_PROOF_SCENARIO.meta.key).toBe(
+			'agent-console.meetup.proof'
+		);
+		expect(AgentConsoleMeetupProofSuite.scenarios).toEqual([
+			{
+				scenario: {
+					key: AGENT_CONSOLE_MEETUP_PROOF_SCENARIO.meta.key,
+					version: AGENT_CONSOLE_MEETUP_PROOF_SCENARIO.meta.version,
+				},
+				required: true,
+				weight: 1,
+			},
+		]);
+	});
+
+	test('serves the seeded agent-console happy path', async () => {
+		const handlers = createAgentConsoleDemoHandlers({
+			projectId: AGENT_CONSOLE_DEMO_PROJECT_ID,
+			organizationId: AGENT_CONSOLE_DEMO_ORGANIZATION_ID,
+			now: (() => {
+				let tick = 0;
+				const base = Date.parse('2026-03-20T09:00:00.000Z');
+
+				return () => new Date(base + tick++ * 60_000);
+			})(),
+		});
+
+		const agents = await handlers.listAgents({
+			projectId: AGENT_CONSOLE_DEMO_PROJECT_ID,
+			organizationId: AGENT_CONSOLE_DEMO_ORGANIZATION_ID,
+			limit: 3,
+		});
+		expect(agents.total).toBeGreaterThan(0);
+
+		const activeAgent = agents.items.find((agent) => agent.status === 'ACTIVE');
+		expect(activeAgent).toBeDefined();
+
+		const run = await handlers.executeAgent({
+			agentId: activeAgent!.id,
+			message: 'Summarize the current autonomous agent status.',
+			context: {
+				projectId: AGENT_CONSOLE_DEMO_PROJECT_ID,
+				organizationId: AGENT_CONSOLE_DEMO_ORGANIZATION_ID,
+			},
+		});
+		expect(run.status).toBe('COMPLETED');
+		expect(run.output).toContain(activeAgent!.name);
+		expect(run.totalTokens).toBeGreaterThan(0);
+	});
+});

package/src/example.ts

@@ -9,7 +9,7 @@ const example = defineExample({
 			'AI agent ops console: tools, agents, runs, logs, and metrics (spec-first, regenerable).',
 		kind: 'template',
 		visibility: 'public',
-		stability: 'experimental',
+		stability: 'beta',
 		owners: ['@platform.core'],
 		tags: ['ai', 'agents', 'tools', 'orchestration'],
 	},
@@ -21,8 +21,7 @@ const example = defineExample({
 	},
 	entrypoints: {
 		packageName: '@contractspec/example.agent-console',
-		feature: './feature',
-		contracts: './contracts',
+		feature: './agent.feature',
 		presentations: './presentations',
 		handlers: './handlers',
 		docs: './docs',

package/src/handlers/agent.handlers.ts

@@ -3,10 +3,34 @@
  *
  * Database-backed handlers for agent management and runs.
  */
+
 import type { DatabasePort } from '@contractspec/lib.runtime-sandbox';
 import { web } from '@contractspec/lib.runtime-sandbox';
+import {
+	CreateAgentCommand,
+	GetAgentQuery,
+	ListAgentsQuery,
+	UpdateAgentCommand,
+} from '../agent/agent.operation';
+import {
+	ExecuteAgentCommand,
+	GetRunMetricsQuery,
+	ListRunsQuery,
+} from '../run/run.operation';
+import { ListToolsQuery } from '../tool/tool.operation';
 
 const { generateId } = web;
+const RUNTIME_AGENT_HANDLER_CONTRACTS = [
+	CreateAgentCommand,
+	GetAgentQuery,
+	ListAgentsQuery,
+	UpdateAgentCommand,
+	ExecuteAgentCommand,
+	ListToolsQuery,
+	ListRunsQuery,
+	GetRunMetricsQuery,
+] as const;
+void RUNTIME_AGENT_HANDLER_CONTRACTS;
 
 // ============ Types ============
 
@@ -111,6 +135,14 @@ export interface ListRunsInput {
 	organizationId?: string;
 	agentId?: string;
 	status?: Run['status'] | 'all';
+	sortBy?:
+		| 'queuedAt'
+		| 'totalTokens'
+		| 'durationMs'
+		| 'estimatedCostUsd'
+		| 'status'
+		| 'agentName';
+	sortDirection?: 'asc' | 'desc';
 	limit?: number;
 	offset?: number;
 }
@@ -190,6 +222,15 @@ interface RunRow extends Record<string, unknown> {
 	completedAt: string | null;
 }
 
+const RUN_SORT_COLUMNS = {
+	queuedAt: 'r.queuedAt',
+	totalTokens: 'r.totalTokens',
+	durationMs: 'r.durationMs',
+	estimatedCostUsd: 'r.estimatedCostUsd',
+	status: 'r.status',
+	agentName: 'a.name',
+} as const;
+
 function rowToAgent(row: AgentRow): Agent {
 	return {
 		id: row.id,
@@ -459,7 +500,15 @@ export function createAgentHandlers(db: DatabasePort) {
 	 * List runs
 	 */
 	async function listRuns(input: ListRunsInput): Promise<ListRunsOutput> {
-		const { projectId, agentId, status, limit = 20, offset = 0 } = input;
+		const {
+			projectId,
+			agentId,
+			status,
+			sortBy,
+			sortDirection = 'desc',
+			limit = 20,
+			offset = 0,
+		} = input;
 
 		let whereClause = 'WHERE r.projectId = ?';
 		const params: (string | number)[] = [projectId];
@@ -481,6 +530,10 @@ export function createAgentHandlers(db: DatabasePort) {
 			)
 		).rows as unknown as { count: number }[];
 		const total = countResult[0]?.count ?? 0;
+		const sortColumn = sortBy
+			? RUN_SORT_COLUMNS[sortBy]
+			: RUN_SORT_COLUMNS.queuedAt;
+		const direction = sortDirection === 'asc' ? 'ASC' : 'DESC';
 
 		const rows = (
 			await db.query(
@@ -488,7 +541,7 @@ export function createAgentHandlers(db: DatabasePort) {
        FROM agent_run r 
        LEFT JOIN agent_definition a ON r.agentId = a.id 
        ${whereClause} 
-       ORDER BY r.queuedAt DESC LIMIT ? OFFSET ?`,
+       ORDER BY ${sortColumn} ${direction}, r.queuedAt DESC LIMIT ? OFFSET ?`,
 				[...params, limit, offset]
 			)
 		).rows as unknown as (RunRow & { agentName: string })[];

package/src/handlers/index.ts

@@ -1,6 +1,23 @@
 /**
  * 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 {
@@ -17,7 +34,7 @@ export {
 	mockListRunsHandler,
 	type RunSummary,
 } from '../run/run.handler';
-
+export { createAgentConsoleDemoHandlers } from '../shared/demo-runtime';
 // Tool handlers and types
 export {
 	mockCreateToolHandler,
@@ -25,6 +42,5 @@ export {
 	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

@@ -24,8 +24,10 @@ 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/proof/index.ts

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