@contractspec/example.agent-console 1.44.0

package/src/agent/agent.entity.ts

@@ -0,0 +1,137 @@
+import {
+  defineEntity,
+  defineEntityEnum,
+  field,
+  index,
+} from '@contractspec/lib.schema';
+
+/**
+ * Agent status for lifecycle management.
+ */
+export const AgentStatusEntityEnum = defineEntityEnum({
+  name: 'AgentStatus',
+  values: ['DRAFT', 'ACTIVE', 'PAUSED', 'ARCHIVED'],
+  description: 'Lifecycle status of the agent',
+});
+
+/**
+ * Agent model provider.
+ */
+export const ModelProviderEntityEnum = defineEntityEnum({
+  name: 'ModelProvider',
+  values: ['OPENAI', 'ANTHROPIC', 'GOOGLE', 'MISTRAL', 'CUSTOM'],
+  description: 'AI model provider',
+});
+
+/**
+ * Agent entity - Represents an AI agent configuration.
+ */
+export const AgentEntity = defineEntity({
+  name: 'Agent',
+  schema: 'agent_console',
+  description:
+    'Represents an AI agent configuration with assigned tools and parameters.',
+  fields: {
+    id: field.id(),
+    organizationId: field.string({
+      description: 'Organization that owns this agent',
+    }),
+    name: field.string({ description: 'Agent name (1-100 chars)' }),
+    slug: field.string({
+      description: 'URL-safe identifier (lowercase, numbers, hyphens)',
+    }),
+    description: field.string({
+      isOptional: true,
+      description: 'Agent description (max 1000 chars)',
+    }),
+    status: field.enum('AgentStatus', { default: 'DRAFT' }),
+    modelProvider: field.enum('ModelProvider', { default: 'OPENAI' }),
+    modelName: field.string({
+      description: "Model identifier: 'gpt-4', 'claude-3-opus', etc.",
+    }),
+    modelConfig: field.json({
+      isOptional: true,
+      description: 'Model parameters: temperature, max_tokens, etc.',
+    }),
+    systemPrompt: field.string({ description: 'System prompt for the agent' }),
+    userPromptTemplate: field.string({
+      isOptional: true,
+      description: 'Template for user prompts',
+    }),
+    toolIds: field.string({
+      isArray: true,
+      isOptional: true,
+      description: 'IDs of assigned tools',
+    }),
+    toolChoice: field.string({
+      default: 'auto',
+      description: "Tool selection mode: 'auto', 'required', 'none'",
+    }),
+    maxIterations: field.int({
+      default: 10,
+      description: 'Maximum iterations per run',
+    }),
+    maxTokensPerRun: field.int({
+      isOptional: true,
+      description: 'Maximum tokens per run',
+    }),
+    timeoutMs: field.int({
+      default: 120000,
+      description: 'Execution timeout in milliseconds',
+    }),
+    version: field.string({ default: '1.0.0', description: 'Agent version' }),
+    tags: field.string({
+      isArray: true,
+      isOptional: true,
+      description: 'Tags for categorization',
+    }),
+    createdAt: field.createdAt(),
+    updatedAt: field.updatedAt(),
+    createdById: field.string({
+      isOptional: true,
+      description: 'User who created this agent',
+    }),
+    tools: field.hasMany('Tool', {
+      description: 'Tools assigned to this agent',
+    }),
+  },
+  indexes: [
+    index.unique(['organizationId', 'slug']),
+    index.on(['organizationId', 'status']),
+    index.on(['modelProvider', 'modelName']),
+  ],
+  enums: [AgentStatusEntityEnum, ModelProviderEntityEnum],
+});
+
+/**
+ * AgentTool join entity - Links agents to their assigned tools.
+ */
+export const AgentToolEntity = defineEntity({
+  name: 'AgentTool',
+  schema: 'agent_console',
+  description: 'Links an agent to its assigned tools with configuration.',
+  fields: {
+    id: field.id(),
+    agentId: field.foreignKey({ description: 'Agent ID' }),
+    toolId: field.foreignKey({ description: 'Tool ID' }),
+    config: field.json({
+      isOptional: true,
+      description: 'Tool-specific configuration for this agent',
+    }),
+    order: field.int({
+      default: 0,
+      description: 'Order of tool in agent tool list',
+    }),
+    isEnabled: field.boolean({
+      default: true,
+      description: 'Whether tool is enabled for this agent',
+    }),
+    createdAt: field.createdAt(),
+    agent: field.belongsTo('Agent', ['agentId'], ['id']),
+    tool: field.belongsTo('Tool', ['toolId'], ['id']),
+  },
+  indexes: [
+    index.unique(['agentId', 'toolId']),
+    index.on(['agentId', 'order']),
+  ],
+});

package/src/agent/agent.enum.ts

@@ -0,0 +1,31 @@
+import { defineEnum } from '@contractspec/lib.schema';
+
+/**
+ * Agent status enum.
+ */
+export const AgentStatusEnum = defineEnum('AgentStatus', [
+  'DRAFT',
+  'ACTIVE',
+  'PAUSED',
+  'ARCHIVED',
+]);
+
+/**
+ * Model provider enum.
+ */
+export const ModelProviderEnum = defineEnum('ModelProvider', [
+  'OPENAI',
+  'ANTHROPIC',
+  'GOOGLE',
+  'MISTRAL',
+  'CUSTOM',
+]);
+
+/**
+ * Tool choice mode enum.
+ */
+export const ToolChoiceEnum = defineEnum('ToolChoice', [
+  'auto',
+  'required',
+  'none',
+]);

package/src/agent/agent.event.ts

@@ -0,0 +1,142 @@
+import { defineEvent, defineSchemaModel } from '@contractspec/lib.contracts';
+import { ScalarTypeEnum } from '@contractspec/lib.schema';
+
+const OWNERS = ['@agent-console-team'] as const;
+
+/**
+ * Payload for agent created event.
+ */
+const AgentCreatedPayload = defineSchemaModel({
+  name: 'AgentCreatedPayload',
+  description: 'Payload for agent created event',
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    organizationId: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false,
+    },
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    slug: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    modelProvider: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false,
+    },
+    modelName: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    toolCount: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    createdById: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+  },
+});
+
+/**
+ * AgentCreatedEvent - A new agent was created.
+ */
+export const AgentCreatedEvent = defineEvent({
+  meta: {
+    key: 'agent-console.agent.created',
+    version: 1,
+    description: 'A new AI agent was configured.',
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['agent', 'created'],
+  },
+  payload: AgentCreatedPayload,
+});
+
+/**
+ * Payload for agent updated event.
+ */
+const AgentUpdatedPayload = defineSchemaModel({
+  name: 'AgentUpdatedPayload',
+  description: 'Payload for agent updated event',
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    organizationId: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false,
+    },
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    status: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    updatedFields: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isArray: true,
+      isOptional: false,
+    },
+    updatedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+  },
+});
+
+/**
+ * AgentUpdatedEvent - An agent was updated.
+ */
+export const AgentUpdatedEvent = defineEvent({
+  meta: {
+    key: 'agent-console.agent.updated',
+    version: 1,
+    description: 'An AI agent configuration was updated.',
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['agent', 'updated'],
+  },
+  payload: AgentUpdatedPayload,
+});
+
+/**
+ * Payload for agent tool assigned event.
+ */
+const AgentToolAssignedPayload = defineSchemaModel({
+  name: 'AgentToolAssignedPayload',
+  description: 'Payload for agent tool assigned event',
+  fields: {
+    agentId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    toolId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    agentName: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    toolName: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    assignedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+  },
+});
+
+/**
+ * AgentToolAssignedEvent - A tool was assigned to an agent.
+ */
+export const AgentToolAssignedEvent = defineEvent({
+  meta: {
+    key: 'agent-console.agent.toolAssigned',
+    version: 1,
+    description: 'A tool was assigned to an agent.',
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['agent', 'tool', 'assigned'],
+  },
+  payload: AgentToolAssignedPayload,
+});
+
+/**
+ * Payload for agent tool removed event.
+ */
+const AgentToolRemovedPayload = defineSchemaModel({
+  name: 'AgentToolRemovedPayload',
+  description: 'Payload for agent tool removed event',
+  fields: {
+    agentId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    toolId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    agentName: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    toolName: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    removedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+  },
+});
+
+/**
+ * AgentToolRemovedEvent - A tool was removed from an agent.
+ */
+export const AgentToolRemovedEvent = defineEvent({
+  meta: {
+    key: 'agent-console.agent.toolRemoved',
+    version: 1,
+    description: 'A tool was removed from an agent.',
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['agent', 'tool', 'removed'],
+  },
+  payload: AgentToolRemovedPayload,
+});

package/src/agent/agent.handler.ts

@@ -0,0 +1,178 @@
+/**
+ * Mock handlers for Agent contracts.
+ */
+import { MOCK_AGENTS } from '../shared/mock-agents';
+import { MOCK_TOOLS } from '../shared/mock-tools';
+
+export interface ListAgentsInput {
+  organizationId: string;
+  status?: 'DRAFT' | 'ACTIVE' | 'PAUSED' | 'ARCHIVED';
+  modelProvider?: 'OPENAI' | 'ANTHROPIC' | 'GOOGLE' | 'MISTRAL' | 'CUSTOM';
+  search?: string;
+  limit?: number;
+  offset?: number;
+}
+
+export interface AgentSummary {
+  id: string;
+  name: string;
+  slug: string;
+  description?: string;
+  status: 'DRAFT' | 'ACTIVE' | 'PAUSED' | 'ARCHIVED';
+  modelProvider: 'OPENAI' | 'ANTHROPIC' | 'GOOGLE' | 'MISTRAL' | 'CUSTOM';
+  modelName: string;
+  version: string;
+  createdAt: Date;
+}
+
+export interface ListAgentsOutput {
+  items: AgentSummary[];
+  total: number;
+  hasMore: boolean;
+}
+
+export interface GetAgentInput {
+  agentId: string;
+  includeTools?: boolean;
+}
+
+export interface AgentToolRef {
+  id: string;
+  name: string;
+  slug: string;
+  description: string;
+  category: string;
+}
+
+export interface AgentWithTools {
+  id: string;
+  organizationId: string;
+  name: string;
+  slug: string;
+  description?: string;
+  status: 'DRAFT' | 'ACTIVE' | 'PAUSED' | 'ARCHIVED';
+  modelProvider: 'OPENAI' | 'ANTHROPIC' | 'GOOGLE' | 'MISTRAL' | 'CUSTOM';
+  modelName: string;
+  modelConfig?: Record<string, unknown>;
+  systemPrompt: string;
+  userPromptTemplate?: string;
+  toolIds?: string[];
+  toolChoice: 'auto' | 'required' | 'none';
+  maxIterations: number;
+  maxTokensPerRun?: number;
+  timeoutMs: number;
+  version: string;
+  tags?: string[];
+  createdAt: Date;
+  updatedAt: Date;
+  tools?: AgentToolRef[];
+}
+
+/**
+ * Mock handler for ListAgentsQuery.
+ */
+export async function mockListAgentsHandler(
+  input: ListAgentsInput
+): Promise<ListAgentsOutput> {
+  const {
+    organizationId,
+    status,
+    modelProvider,
+    search,
+    limit = 20,
+    offset = 0,
+  } = input;
+
+  let filtered = MOCK_AGENTS.filter((a) => a.organizationId === organizationId);
+  if (status) filtered = filtered.filter((a) => a.status === status);
+  if (modelProvider)
+    filtered = filtered.filter((a) => a.modelProvider === modelProvider);
+  if (search) {
+    const q = search.toLowerCase();
+    filtered = filtered.filter(
+      (a) =>
+        a.name.toLowerCase().includes(q) ||
+        a.description?.toLowerCase().includes(q) ||
+        a.tags?.some((t) => t.toLowerCase().includes(q))
+    );
+  }
+
+  const total = filtered.length;
+  const items = filtered.slice(offset, offset + limit).map((a) => ({
+    id: a.id,
+    name: a.name,
+    slug: a.slug,
+    description: a.description,
+    status: a.status,
+    modelProvider: a.modelProvider,
+    modelName: a.modelName,
+    version: a.version,
+    createdAt: a.createdAt,
+  }));
+
+  return { items, total, hasMore: offset + limit < total };
+}
+
+/**
+ * Mock handler for GetAgentQuery.
+ */
+export async function mockGetAgentHandler(
+  input: GetAgentInput
+): Promise<AgentWithTools> {
+  const agent = MOCK_AGENTS.find((a) => a.id === input.agentId);
+  if (!agent) throw new Error('AGENT_NOT_FOUND');
+
+  const result: AgentWithTools = { ...agent, toolIds: ['tool-1', 'tool-2'] };
+  if (input.includeTools) {
+    result.tools = MOCK_TOOLS.slice(0, 2).map((t) => ({
+      id: t.id,
+      name: t.name,
+      slug: t.slug,
+      description: t.description,
+      category: t.category,
+    }));
+  }
+  return result;
+}
+
+/**
+ * Mock handler for CreateAgentCommand.
+ */
+export async function mockCreateAgentHandler(input: {
+  organizationId: string;
+  name: string;
+  slug: string;
+  description?: string;
+  modelProvider: 'OPENAI' | 'ANTHROPIC' | 'GOOGLE' | 'MISTRAL' | 'CUSTOM';
+  modelName: string;
+  systemPrompt: string;
+}) {
+  const exists = MOCK_AGENTS.some(
+    (a) => a.organizationId === input.organizationId && a.slug === input.slug
+  );
+  if (exists) throw new Error('SLUG_EXISTS');
+  return {
+    id: `agent-${Date.now()}`,
+    name: input.name,
+    slug: input.slug,
+    status: 'DRAFT' as const,
+  };
+}
+
+/**
+ * Mock handler for UpdateAgentCommand.
+ */
+export async function mockUpdateAgentHandler(input: {
+  agentId: string;
+  name?: string;
+  status?: 'DRAFT' | 'ACTIVE' | 'PAUSED' | 'ARCHIVED';
+}) {
+  const agent = MOCK_AGENTS.find((a) => a.id === input.agentId);
+  if (!agent) throw new Error('AGENT_NOT_FOUND');
+  return {
+    id: agent.id,
+    name: input.name ?? agent.name,
+    status: input.status ?? agent.status,
+    updatedAt: new Date(),
+  };
+}