@lssm/example.agent-console 0.0.0-canary-20251215234340 → 0.0.0-canary-20251216024228

package/src/agent/agent.contracts.ts

@@ -0,0 +1,275 @@
+import { defineCommand, defineQuery } from '@lssm/lib.contracts/spec';
+import { defineSchemaModel, ScalarTypeEnum } from '@lssm/lib.schema';
+import { AgentStatusEnum, ModelProviderEnum } from './agent.enum';
+import {
+  AgentSummaryModel,
+  AgentWithToolsModel,
+  CreateAgentInputModel,
+  UpdateAgentInputModel,
+} from './agent.schema';
+import { AgentCreatedEvent } from './agent.event';
+
+const OWNERS = ['@agent-console-team'] as const;
+
+/**
+ * CreateAgentCommand - Creates a new agent configuration.
+ */
+export const CreateAgentCommand = defineCommand({
+  meta: {
+    name: 'agent.agent.create',
+    version: 1,
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['agent', 'create'],
+    description: 'Creates a new AI agent configuration.',
+    goal: 'Allow users to define new AI agents with specific models and tools.',
+    context: 'Called from the agent builder UI when creating a new agent.',
+  },
+  io: {
+    input: CreateAgentInputModel,
+    output: defineSchemaModel({
+      name: 'CreateAgentOutput',
+      fields: {
+        id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+        name: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+        slug: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+        status: { type: AgentStatusEnum, isOptional: false },
+      },
+    }),
+    errors: {
+      SLUG_EXISTS: {
+        description:
+          'An agent with this slug already exists in the organization',
+        http: 409,
+        gqlCode: 'SLUG_EXISTS',
+        when: 'Slug is already taken',
+      },
+    },
+  },
+  policy: { auth: 'user' },
+  sideEffects: {
+    emits: [
+      {
+        // name: 'agent.created',
+        // version: 1,
+        // payload: AgentSummaryModel,
+        ref: AgentCreatedEvent,
+        when: 'Agent is successfully created',
+      },
+    ],
+    audit: ['agent.created'],
+  },
+});
+
+/**
+ * UpdateAgentCommand - Updates an existing agent.
+ */
+export const UpdateAgentCommand = defineCommand({
+  meta: {
+    name: 'agent.agent.update',
+    version: 1,
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['agent', 'update'],
+    description: 'Updates an existing AI agent configuration.',
+    goal: 'Allow users to modify agent settings and configuration.',
+    context: 'Called from the agent settings UI.',
+  },
+  io: {
+    input: UpdateAgentInputModel,
+    output: defineSchemaModel({
+      name: 'UpdateAgentOutput',
+      fields: {
+        id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+        name: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+        status: { type: AgentStatusEnum, isOptional: false },
+        updatedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+      },
+    }),
+    errors: {
+      AGENT_NOT_FOUND: {
+        description: 'The specified agent does not exist',
+        http: 404,
+        gqlCode: 'AGENT_NOT_FOUND',
+        when: 'Agent ID is invalid',
+      },
+    },
+  },
+  policy: { auth: 'user' },
+  sideEffects: {
+    emits: [
+      {
+        name: 'agent.updated',
+        version: 1,
+        when: 'Agent is updated',
+        payload: AgentSummaryModel,
+      },
+    ],
+    audit: ['agent.updated'],
+  },
+});
+
+/**
+ * GetAgentQuery - Retrieves an agent by ID.
+ */
+export const GetAgentQuery = defineQuery({
+  meta: {
+    name: 'agent.agent.get',
+    version: 1,
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['agent', 'get'],
+    description: 'Retrieves an agent by its ID.',
+    goal: 'View detailed agent configuration.',
+    context: 'Called when viewing agent details or editing.',
+  },
+  io: {
+    input: defineSchemaModel({
+      name: 'GetAgentInput',
+      fields: {
+        agentId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+        includeTools: { type: ScalarTypeEnum.Boolean(), isOptional: true },
+      },
+    }),
+    output: AgentWithToolsModel,
+    errors: {
+      AGENT_NOT_FOUND: {
+        description: 'The specified agent does not exist',
+        http: 404,
+        gqlCode: 'AGENT_NOT_FOUND',
+        when: 'Agent ID is invalid',
+      },
+    },
+  },
+  policy: { auth: 'user' },
+});
+
+/**
+ * ListAgentsQuery - Lists agents for an organization.
+ */
+export const ListAgentsQuery = defineQuery({
+  meta: {
+    name: 'agent.agent.list',
+    version: 1,
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['agent', 'list'],
+    description: 'Lists agents for an organization with optional filtering.',
+    goal: 'Browse and search available agents.',
+    context: 'Agent list/dashboard view.',
+  },
+  io: {
+    input: defineSchemaModel({
+      name: 'ListAgentsInput',
+      fields: {
+        organizationId: {
+          type: ScalarTypeEnum.String_unsecure(),
+          isOptional: false,
+        },
+        status: { type: AgentStatusEnum, isOptional: true },
+        modelProvider: { type: ModelProviderEnum, isOptional: true },
+        search: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+        limit: {
+          type: ScalarTypeEnum.Int_unsecure(),
+          isOptional: true,
+          defaultValue: 20,
+        },
+        offset: {
+          type: ScalarTypeEnum.Int_unsecure(),
+          isOptional: true,
+          defaultValue: 0,
+        },
+      },
+    }),
+    output: defineSchemaModel({
+      name: 'ListAgentsOutput',
+      fields: {
+        items: { type: AgentSummaryModel, isArray: true, isOptional: false },
+        total: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+        hasMore: { type: ScalarTypeEnum.Boolean(), isOptional: false },
+      },
+    }),
+  },
+  policy: { auth: 'user' },
+});
+
+/**
+ * AssignToolToAgentCommand - Assigns a tool to an agent.
+ */
+export const AssignToolToAgentCommand = defineCommand({
+  meta: {
+    name: 'agent.agent.assignTool',
+    version: 1,
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['agent', 'tool', 'assign'],
+    description: 'Assigns a tool to an agent with optional configuration.',
+    goal: 'Enable agents to use specific tools.',
+    context: 'Agent configuration UI - tool selection.',
+  },
+  io: {
+    input: defineSchemaModel({
+      name: 'AssignToolToAgentInput',
+      fields: {
+        agentId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+        toolId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+        config: { type: ScalarTypeEnum.JSONObject(), isOptional: true },
+        order: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true },
+      },
+    }),
+    output: defineSchemaModel({
+      name: 'AssignToolToAgentOutput',
+      fields: {
+        agentToolId: {
+          type: ScalarTypeEnum.String_unsecure(),
+          isOptional: false,
+        },
+        agentId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+        toolId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+      },
+    }),
+    errors: {
+      TOOL_ALREADY_ASSIGNED: {
+        description: 'This tool is already assigned to the agent',
+        http: 409,
+        gqlCode: 'TOOL_ALREADY_ASSIGNED',
+        when: 'Tool assignment already exists',
+      },
+    },
+  },
+  policy: { auth: 'user' },
+  sideEffects: { audit: ['agent.tool.assigned'] },
+});
+
+/**
+ * RemoveToolFromAgentCommand - Removes a tool from an agent.
+ */
+export const RemoveToolFromAgentCommand = defineCommand({
+  meta: {
+    name: 'agent.agent.removeTool',
+    version: 1,
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['agent', 'tool', 'remove'],
+    description: 'Removes a tool assignment from an agent.',
+    goal: 'Disable specific tools for an agent.',
+    context: 'Agent configuration UI - tool management.',
+  },
+  io: {
+    input: defineSchemaModel({
+      name: 'RemoveToolFromAgentInput',
+      fields: {
+        agentId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+        toolId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+      },
+    }),
+    output: defineSchemaModel({
+      name: 'RemoveToolFromAgentOutput',
+      fields: {
+        success: { type: ScalarTypeEnum.Boolean(), isOptional: false },
+      },
+    }),
+  },
+  policy: { auth: 'user' },
+  sideEffects: { audit: ['agent.tool.removed'] },
+});

package/src/agent/agent.entity.ts

@@ -0,0 +1,84 @@
+import { defineEntity, defineEntityEnum, field, index } from '@lssm/lib.schema/entity';
+
+/**
+ * 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 '@lssm/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,109 @@
+import { defineEvent, defineSchemaModel } from '@lssm/lib.contracts';
+import { ScalarTypeEnum } from '@lssm/lib.schema';
+
+/**
+ * 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({
+  name: 'agent.agent.created',
+  version: 1,
+  description: 'A new AI agent was configured.',
+  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({
+  name: 'agent.agent.updated',
+  version: 1,
+  description: 'An AI agent configuration was 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({
+  name: 'agent.agent.toolAssigned',
+  version: 1,
+  description: 'A tool was assigned to an agent.',
+  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({
+  name: 'agent.agent.toolRemoved',
+  version: 1,
+  description: 'A tool was removed from an agent.',
+  payload: AgentToolRemovedPayload,
+});
+
+

package/src/{handlers/agent.handlers.ts → agent/agent.handler.ts}

@@ -1,9 +1,9 @@
 /**
- * Mock handlers for Agent contracts
+ * Mock handlers for Agent contracts.
  */
-import { MOCK_AGENTS, MOCK_TOOLS } from './mock-data';
+import { MOCK_AGENTS } from '../shared/mock-agents';
+import { MOCK_TOOLS } from '../shared/mock-tools';
 
-// Types inferred from contract schemas
 export interface ListAgentsInput {
   organizationId: string;
   status?: 'DRAFT' | 'ACTIVE' | 'PAUSED' | 'ARCHIVED';
@@ -69,37 +69,18 @@ export interface AgentWithTools {
 }
 
 /**
- * Mock handler for ListAgentsQuery
+ * Mock handler for ListAgentsQuery.
  */
-export async function mockListAgentsHandler(
-  input: ListAgentsInput
-): Promise<ListAgentsOutput> {
-  const {
-    organizationId,
-    status,
-    modelProvider,
-    search,
-    limit = 20,
-    offset = 0,
-  } = input;
+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 (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))
+      (a) => a.name.toLowerCase().includes(q) || a.description?.toLowerCase().includes(q) || a.tags?.some((t) => t.toLowerCase().includes(q))
     );
   }
 
@@ -116,30 +97,17 @@ export async function mockListAgentsHandler(
     createdAt: a.createdAt,
   }));
 
-  return {
-    items,
-    total,
-    hasMore: offset + limit < total,
-  };
+  return { items, total, hasMore: offset + limit < total };
 }
 
 /**
- * Mock handler for GetAgentQuery
+ * Mock handler for GetAgentQuery.
  */
-export async function mockGetAgentHandler(
-  input: GetAgentInput
-): Promise<AgentWithTools> {
+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');
 
-  if (!agent) {
-    throw new Error('AGENT_NOT_FOUND');
-  }
-
-  const result: AgentWithTools = {
-    ...agent,
-    toolIds: ['tool-1', 'tool-2'],
-  };
-
+  const result: AgentWithTools = { ...agent, toolIds: ['tool-1', 'tool-2'] };
   if (input.includeTools) {
     result.tools = MOCK_TOOLS.slice(0, 2).map((t) => ({
       id: t.id,
@@ -149,12 +117,11 @@ export async function mockGetAgentHandler(
       category: t.category,
     }));
   }
-
   return result;
 }
 
 /**
- * Mock handler for CreateAgentCommand
+ * Mock handler for CreateAgentCommand.
  */
 export async function mockCreateAgentHandler(input: {
   organizationId: string;
@@ -165,39 +132,17 @@ export async function mockCreateAgentHandler(input: {
   modelName: string;
   systemPrompt: string;
 }) {
-  // Simulate slug collision check
-  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,
-  };
+  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
+ * Mock handler for UpdateAgentCommand.
  */
-export async function mockUpdateAgentHandler(input: {
-  agentId: string;
-  name?: string;
-  status?: 'DRAFT' | 'ACTIVE' | 'PAUSED' | 'ARCHIVED';
-}) {
+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(),
-  };
+  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() };
 }
+