@contractspec/example.agent-console 1.44.0

package/src/run/index.ts

@@ -0,0 +1,68 @@
+/**
+ * Run domain - Agent execution and monitoring.
+ */
+
+// Enums
+export {
+  RunStatusEnum,
+  RunStepTypeEnum,
+  LogLevelEnum,
+  GranularityEnum,
+} from './run.enum';
+
+// Schema models
+export {
+  RunInputModel,
+  RunStepModel,
+  RunLogModel,
+  RunAgentRefModel,
+  RunModel,
+  RunSummaryModel,
+  TimelineDataPointModel,
+} from './run.schema';
+
+// Contracts
+export {
+  ExecuteAgentCommand,
+  CancelRunCommand,
+  GetRunQuery,
+  ListRunsQuery,
+  GetRunStepsQuery,
+  GetRunLogsQuery,
+  GetRunMetricsQuery,
+} from './run.operation';
+
+// Events
+export {
+  RunStartedEvent,
+  RunCompletedEvent,
+  RunFailedEvent,
+  RunCancelledEvent,
+  ToolInvokedEvent,
+  ToolCompletedEvent,
+  MessageGeneratedEvent,
+} from './run.event';
+
+// Entities
+export {
+  RunStatusEntityEnum,
+  RunStepTypeEntityEnum,
+  LogLevelEntityEnum,
+  RunEntity,
+  RunStepEntity,
+  RunLogEntity,
+} from './run.entity';
+
+// Presentations
+export { RunListPresentation, RunDetailPresentation } from './run.presentation';
+
+// Handlers
+export {
+  mockListRunsHandler,
+  mockGetRunHandler,
+  mockExecuteAgentHandler,
+  mockCancelRunHandler,
+  type ListRunsInput,
+  type RunSummary,
+  type ListRunsOutput,
+} from './run.handler';

package/src/run/run.entity.ts

@@ -0,0 +1,175 @@
+import {
+  defineEntity,
+  defineEntityEnum,
+  field,
+  index,
+} from '@contractspec/lib.schema';
+
+/**
+ * Run status enum for entities.
+ */
+export const RunStatusEntityEnum = defineEntityEnum({
+  name: 'RunStatus',
+  values: [
+    'QUEUED',
+    'IN_PROGRESS',
+    'COMPLETED',
+    'FAILED',
+    'CANCELLED',
+    'EXPIRED',
+  ],
+  description: 'Status of an agent run',
+});
+
+/**
+ * Run step type enum for entities.
+ */
+export const RunStepTypeEntityEnum = defineEntityEnum({
+  name: 'RunStepType',
+  values: ['MESSAGE_CREATION', 'TOOL_CALL', 'TOOL_RESULT', 'ERROR'],
+  description: 'Type of run step',
+});
+
+/**
+ * Log level enum for entities.
+ */
+export const LogLevelEntityEnum = defineEntityEnum({
+  name: 'LogLevel',
+  values: ['DEBUG', 'INFO', 'WARN', 'ERROR'],
+  description: 'Log level',
+});
+
+/**
+ * Run entity - Represents an agent execution.
+ */
+export const RunEntity = defineEntity({
+  name: 'Run',
+  schema: 'agent_console',
+  description: 'An execution of an agent with input/output and metrics.',
+  fields: {
+    id: field.id(),
+    organizationId: field.string({ description: 'Organization ID' }),
+    agentId: field.foreignKey({ description: 'Agent being executed' }),
+    userId: field.string({
+      isOptional: true,
+      description: 'User who initiated the run',
+    }),
+    sessionId: field.string({
+      isOptional: true,
+      description: 'Conversation session ID',
+    }),
+    input: field.json({ description: 'Input data for the run' }),
+    output: field.json({
+      isOptional: true,
+      description: 'Output result from the run',
+    }),
+    status: field.enum('RunStatus', { default: 'QUEUED' }),
+    errorMessage: field.string({
+      isOptional: true,
+      description: 'Error message if failed',
+    }),
+    errorCode: field.string({
+      isOptional: true,
+      description: 'Error code if failed',
+    }),
+    totalTokens: field.int({ default: 0, description: 'Total tokens used' }),
+    promptTokens: field.int({ default: 0, description: 'Prompt tokens used' }),
+    completionTokens: field.int({
+      default: 0,
+      description: 'Completion tokens used',
+    }),
+    totalIterations: field.int({
+      default: 0,
+      description: 'Number of iterations',
+    }),
+    durationMs: field.int({
+      isOptional: true,
+      description: 'Execution duration in ms',
+    }),
+    estimatedCostUsd: field.float({
+      isOptional: true,
+      description: 'Estimated cost in USD',
+    }),
+    queuedAt: field.dateTime({ description: 'When run was queued' }),
+    startedAt: field.dateTime({
+      isOptional: true,
+      description: 'When run started executing',
+    }),
+    completedAt: field.dateTime({
+      isOptional: true,
+      description: 'When run completed',
+    }),
+    metadata: field.json({
+      isOptional: true,
+      description: 'Additional metadata',
+    }),
+    agent: field.belongsTo('Agent', ['agentId'], ['id']),
+    steps: field.hasMany('RunStep', { description: 'Execution steps' }),
+    logs: field.hasMany('RunLog', { description: 'Execution logs' }),
+  },
+  indexes: [
+    index.on(['organizationId', 'agentId', 'queuedAt']),
+    index.on(['organizationId', 'status']),
+    index.on(['agentId', 'status']),
+    index.on(['sessionId']),
+  ],
+  enums: [RunStatusEntityEnum],
+});
+
+/**
+ * RunStep entity - Individual step in a run.
+ */
+export const RunStepEntity = defineEntity({
+  name: 'RunStep',
+  schema: 'agent_console',
+  description: 'An individual step in an agent run.',
+  fields: {
+    id: field.id(),
+    runId: field.foreignKey({ description: 'Parent run' }),
+    stepNumber: field.int({ description: 'Step sequence number' }),
+    type: field.enum('RunStepType'),
+    toolId: field.string({
+      isOptional: true,
+      description: 'Tool used in this step',
+    }),
+    toolName: field.string({ isOptional: true, description: 'Tool name' }),
+    input: field.json({ isOptional: true, description: 'Step input' }),
+    output: field.json({ isOptional: true, description: 'Step output' }),
+    status: field.enum('RunStatus'),
+    errorMessage: field.string({ isOptional: true }),
+    tokensUsed: field.int({ default: 0 }),
+    durationMs: field.int({ isOptional: true }),
+    startedAt: field.dateTime(),
+    completedAt: field.dateTime({ isOptional: true }),
+    run: field.belongsTo('Run', ['runId'], ['id']),
+  },
+  indexes: [index.on(['runId', 'stepNumber'])],
+  enums: [RunStepTypeEntityEnum],
+});
+
+/**
+ * RunLog entity - Log entry for a run.
+ */
+export const RunLogEntity = defineEntity({
+  name: 'RunLog',
+  schema: 'agent_console',
+  description: 'A log entry for an agent run.',
+  fields: {
+    id: field.id(),
+    runId: field.foreignKey({ description: 'Parent run' }),
+    stepId: field.string({ isOptional: true, description: 'Related step' }),
+    level: field.enum('LogLevel'),
+    message: field.string({ description: 'Log message' }),
+    data: field.json({ isOptional: true, description: 'Additional log data' }),
+    source: field.string({
+      isOptional: true,
+      description: 'Log source component',
+    }),
+    traceId: field.string({ isOptional: true }),
+    spanId: field.string({ isOptional: true }),
+    timestamp: field.dateTime(),
+    run: field.belongsTo('Run', ['runId'], ['id']),
+  },
+  indexes: [index.on(['runId', 'timestamp']), index.on(['runId', 'level'])],
+  enums: [LogLevelEntityEnum],
+});

package/src/run/run.enum.ts

@@ -0,0 +1,43 @@
+import { defineEnum } from '@contractspec/lib.schema';
+
+/**
+ * Run status enum.
+ */
+export const RunStatusEnum = defineEnum('RunStatus', [
+  'QUEUED',
+  'IN_PROGRESS',
+  'COMPLETED',
+  'FAILED',
+  'CANCELLED',
+  'EXPIRED',
+]);
+
+/**
+ * Run step type enum.
+ */
+export const RunStepTypeEnum = defineEnum('RunStepType', [
+  'MESSAGE_CREATION',
+  'TOOL_CALL',
+  'TOOL_RESULT',
+  'ERROR',
+]);
+
+/**
+ * Log level enum.
+ */
+export const LogLevelEnum = defineEnum('LogLevel', [
+  'DEBUG',
+  'INFO',
+  'WARN',
+  'ERROR',
+]);
+
+/**
+ * Granularity enum for metrics.
+ */
+export const GranularityEnum = defineEnum('Granularity', [
+  'hour',
+  'day',
+  'week',
+  'month',
+]);

package/src/run/run.event.ts

@@ -0,0 +1,264 @@
+import { defineEvent, defineSchemaModel } from '@contractspec/lib.contracts';
+import { ScalarTypeEnum, defineEnum } from '@contractspec/lib.schema';
+
+const OWNERS = ['@agent-console-team'] as const;
+
+/**
+ * Payload for run started event.
+ */
+const RunStartedPayload = defineSchemaModel({
+  name: 'RunStartedPayload',
+  description: 'Payload for run started event',
+  fields: {
+    runId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    organizationId: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false,
+    },
+    agentId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    agentName: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    userId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    sessionId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    input: { type: ScalarTypeEnum.JSONObject(), isOptional: false },
+    startedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+  },
+});
+
+/**
+ * RunStartedEvent - An agent run was started.
+ */
+export const RunStartedEvent = defineEvent({
+  meta: {
+    key: 'agent.run.started',
+    version: 1,
+    description: 'An agent run was started.',
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['run', 'started'],
+  },
+  payload: RunStartedPayload,
+});
+
+/**
+ * Payload for run completed event.
+ */
+const RunCompletedPayload = defineSchemaModel({
+  name: 'RunCompletedPayload',
+  description: 'Payload for run completed event',
+  fields: {
+    runId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    organizationId: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false,
+    },
+    agentId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    agentName: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    userId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    output: { type: ScalarTypeEnum.JSONObject(), isOptional: false },
+    totalTokens: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    promptTokens: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    completionTokens: {
+      type: ScalarTypeEnum.Int_unsecure(),
+      isOptional: false,
+    },
+    totalIterations: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    durationMs: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    estimatedCostUsd: {
+      type: ScalarTypeEnum.Float_unsecure(),
+      isOptional: true,
+    },
+    completedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+  },
+});
+
+/**
+ * RunCompletedEvent - An agent run completed successfully.
+ */
+export const RunCompletedEvent = defineEvent({
+  meta: {
+    key: 'agent.run.completed',
+    version: 1,
+    description: 'An agent run completed successfully.',
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['run', 'completed'],
+  },
+  payload: RunCompletedPayload,
+});
+
+/**
+ * Payload for run failed event.
+ */
+const RunFailedPayload = defineSchemaModel({
+  name: 'RunFailedPayload',
+  description: 'Payload for run failed event',
+  fields: {
+    runId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    organizationId: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false,
+    },
+    agentId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    agentName: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    userId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    errorMessage: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    errorCode: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    totalTokens: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    totalIterations: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    durationMs: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true },
+    failedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+  },
+});
+
+/**
+ * RunFailedEvent - An agent run failed.
+ */
+export const RunFailedEvent = defineEvent({
+  meta: {
+    key: 'agent.run.failed',
+    version: 1,
+    description: 'An agent run encountered an error.',
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['run', 'failed'],
+  },
+  payload: RunFailedPayload,
+});
+
+/**
+ * Payload for run cancelled event.
+ */
+const RunCancelledPayload = defineSchemaModel({
+  name: 'RunCancelledPayload',
+  description: 'Payload for run cancelled event',
+  fields: {
+    runId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    organizationId: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false,
+    },
+    agentId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    userId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    cancelledBy: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    reason: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    totalTokens: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    totalIterations: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    cancelledAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+  },
+});
+
+/**
+ * RunCancelledEvent - An agent run was cancelled.
+ */
+export const RunCancelledEvent = defineEvent({
+  meta: {
+    key: 'agent.run.cancelled',
+    version: 1,
+    description: 'An agent run was cancelled by the user.',
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['run', 'cancelled'],
+  },
+  payload: RunCancelledPayload,
+});
+
+/**
+ * Payload for tool invoked event.
+ */
+const ToolInvokedPayload = defineSchemaModel({
+  name: 'ToolInvokedPayload',
+  description: 'Payload for tool invoked event',
+  fields: {
+    runId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    stepId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    toolId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    toolName: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    input: { type: ScalarTypeEnum.JSONObject(), isOptional: false },
+    invokedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+  },
+});
+
+/**
+ * ToolInvokedEvent - A tool was invoked during a run.
+ */
+export const ToolInvokedEvent = defineEvent({
+  meta: {
+    key: 'agent.run.toolInvoked',
+    version: 1,
+    description: 'A tool was invoked during an agent run.',
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['run', 'tool', 'invoked'],
+  },
+  payload: ToolInvokedPayload,
+});
+
+/**
+ * Payload for tool completed event.
+ */
+const ToolCompletedPayload = defineSchemaModel({
+  name: 'ToolCompletedPayload',
+  description: 'Payload for tool completed event',
+  fields: {
+    runId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    stepId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    toolId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    toolName: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    success: { type: ScalarTypeEnum.Boolean(), isOptional: false },
+    output: { type: ScalarTypeEnum.JSONObject(), isOptional: true },
+    errorMessage: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    durationMs: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    completedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+  },
+});
+
+/**
+ * ToolCompletedEvent - A tool invocation completed.
+ */
+export const ToolCompletedEvent = defineEvent({
+  meta: {
+    key: 'agent.run.toolCompleted',
+    version: 1,
+    description: 'A tool invocation completed during an agent run.',
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['run', 'tool', 'completed'],
+  },
+  payload: ToolCompletedPayload,
+});
+
+/**
+ * Message type enum.
+ */
+const MessageTypeEnum = defineEnum('MessageType', ['assistant', 'system']);
+
+/**
+ * Payload for message generated event.
+ */
+const MessageGeneratedPayload = defineSchemaModel({
+  name: 'MessageGeneratedPayload',
+  description: 'Payload for message generated event',
+  fields: {
+    runId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    stepId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    messageType: { type: MessageTypeEnum, isOptional: false },
+    content: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    tokensUsed: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    generatedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+  },
+});
+
+/**
+ * MessageGeneratedEvent - Agent generated a message.
+ */
+export const MessageGeneratedEvent = defineEvent({
+  meta: {
+    key: 'agent.run.messageGenerated',
+    version: 1,
+    description: 'An agent generated a message during a run.',
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['run', 'message', 'generated'],
+  },
+  payload: MessageGeneratedPayload,
+});

package/src/run/run.handler.ts

@@ -0,0 +1,138 @@
+/**
+ * Mock handlers for Run contracts.
+ */
+import { MOCK_RUNS } from '../shared/mock-runs';
+import { MOCK_AGENTS } from '../shared/mock-agents';
+
+export interface ListRunsInput {
+  organizationId?: string;
+  agentId?: string;
+  userId?: string;
+  sessionId?: string;
+  status?:
+    | 'QUEUED'
+    | 'IN_PROGRESS'
+    | 'COMPLETED'
+    | 'FAILED'
+    | 'CANCELLED'
+    | 'EXPIRED';
+  startDate?: Date;
+  endDate?: Date;
+  limit?: number;
+  offset?: number;
+}
+
+export interface RunSummary {
+  id: string;
+  agentId: string;
+  agentName: string;
+  status:
+    | 'QUEUED'
+    | 'IN_PROGRESS'
+    | 'COMPLETED'
+    | 'FAILED'
+    | 'CANCELLED'
+    | 'EXPIRED';
+  totalTokens: number;
+  durationMs?: number;
+  estimatedCostUsd?: number;
+  queuedAt: Date;
+  completedAt?: Date;
+}
+
+export interface ListRunsOutput {
+  items: RunSummary[];
+  total: number;
+  hasMore: boolean;
+}
+
+/**
+ * Mock handler for ListRunsQuery.
+ */
+export async function mockListRunsHandler(
+  input: ListRunsInput
+): Promise<ListRunsOutput> {
+  const { agentId, status, limit = 20, offset = 0 } = input;
+
+  let filtered = [...MOCK_RUNS];
+  if (agentId) filtered = filtered.filter((r) => r.agentId === agentId);
+  if (status) filtered = filtered.filter((r) => r.status === status);
+
+  const total = filtered.length;
+  const items = filtered.slice(offset, offset + limit).map((r) => {
+    const agent = MOCK_AGENTS.find((a) => a.id === r.agentId);
+    return {
+      id: r.id,
+      agentId: r.agentId,
+      agentName: agent?.name ?? 'Unknown',
+      status: r.status,
+      totalTokens: r.totalTokens,
+      durationMs: r.durationMs,
+      estimatedCostUsd: r.estimatedCostUsd,
+      queuedAt: r.queuedAt,
+      completedAt: r.completedAt,
+    };
+  });
+
+  return { items, total, hasMore: offset + limit < total };
+}
+
+/**
+ * Mock handler for GetRunQuery.
+ */
+export async function mockGetRunHandler(input: {
+  runId: string;
+  includeSteps?: boolean;
+  includeLogs?: boolean;
+}) {
+  const run = MOCK_RUNS.find((r) => r.id === input.runId);
+  if (!run) throw new Error('RUN_NOT_FOUND');
+
+  const agent = MOCK_AGENTS.find((a) => a.id === run.agentId);
+  return {
+    ...run,
+    agent: agent
+      ? {
+          id: agent.id,
+          name: agent.name,
+          modelProvider: agent.modelProvider,
+          modelName: agent.modelName,
+        }
+      : undefined,
+    steps: input.includeSteps ? run.steps : undefined,
+    logs: input.includeLogs ? run.logs : undefined,
+  };
+}
+
+/**
+ * Mock handler for ExecuteAgentCommand.
+ */
+export async function mockExecuteAgentHandler(input: {
+  agentId: string;
+  input: { message: string; context?: Record<string, unknown> };
+}) {
+  const agent = MOCK_AGENTS.find((a) => a.id === input.agentId);
+  if (!agent) throw new Error('AGENT_NOT_FOUND');
+  if (agent.status !== 'ACTIVE') throw new Error('AGENT_NOT_ACTIVE');
+
+  return {
+    runId: `run-${Date.now()}`,
+    status: 'QUEUED' as const,
+    estimatedWaitMs: 500,
+  };
+}
+
+/**
+ * Mock handler for CancelRunCommand.
+ */
+export async function mockCancelRunHandler(input: {
+  runId: string;
+  reason?: string;
+}) {
+  const run = MOCK_RUNS.find((r) => r.id === input.runId);
+  if (!run) throw new Error('RUN_NOT_FOUND');
+  if (!['QUEUED', 'IN_PROGRESS'].includes(run.status))
+    throw new Error('RUN_NOT_CANCELLABLE');
+
+  return { success: true, status: 'CANCELLED' as const };
+}