@lssm/example.agent-console 0.0.0-canary-20251206160926

package/src/contracts/tool.ts

@@ -0,0 +1,392 @@
+import { defineCommand, defineQuery } from '@lssm/lib.contracts/spec';
+import {
+  defineSchemaModel,
+  ScalarTypeEnum,
+  defineEnum,
+} from '@lssm/lib.schema';
+
+const OWNERS = ['agent-console-team'] as const;
+
+// ============ Enums ============
+
+export const ToolCategoryEnum = defineEnum('ToolCategory', [
+  'RETRIEVAL',
+  'COMPUTATION',
+  'COMMUNICATION',
+  'INTEGRATION',
+  'UTILITY',
+  'CUSTOM',
+]);
+
+export const ToolStatusEnum = defineEnum('ToolStatus', [
+  'DRAFT',
+  'ACTIVE',
+  'DEPRECATED',
+  'DISABLED',
+]);
+
+export const ImplementationTypeEnum = defineEnum('ImplementationType', [
+  'http',
+  'function',
+  'workflow',
+]);
+
+// ============ Schemas ============
+
+export const ToolModel = defineSchemaModel({
+  name: 'Tool',
+  description: 'AI tool definition',
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    organizationId: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false,
+    },
+    name: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    slug: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    description: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    category: { type: ToolCategoryEnum, isOptional: false },
+    status: { type: ToolStatusEnum, isOptional: false },
+    parametersSchema: { type: ScalarTypeEnum.JSONObject(), isOptional: false },
+    outputSchema: { type: ScalarTypeEnum.JSONObject(), isOptional: true },
+    implementationType: { type: ImplementationTypeEnum, isOptional: false },
+    implementationConfig: {
+      type: ScalarTypeEnum.JSONObject(),
+      isOptional: false,
+    },
+    maxInvocationsPerMinute: {
+      type: ScalarTypeEnum.Int_unsecure(),
+      isOptional: true,
+    },
+    timeoutMs: {
+      type: ScalarTypeEnum.Int_unsecure(),
+      isOptional: false,
+      defaultValue: 30000,
+    },
+    version: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    tags: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isArray: true,
+      isOptional: true,
+    },
+    createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+    updatedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+  },
+});
+
+export const ToolSummaryModel = defineSchemaModel({
+  name: 'ToolSummary',
+  description: 'Summary of a tool for list views',
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    name: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    slug: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    description: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    category: { type: ToolCategoryEnum, isOptional: false },
+    status: { type: ToolStatusEnum, isOptional: false },
+    version: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+  },
+});
+
+export const CreateToolInputModel = defineSchemaModel({
+  name: 'CreateToolInput',
+  description: 'Input for creating a tool',
+  fields: {
+    organizationId: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false,
+    },
+    name: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    slug: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    description: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    category: { type: ToolCategoryEnum, isOptional: true },
+    parametersSchema: { type: ScalarTypeEnum.JSONObject(), isOptional: false },
+    outputSchema: { type: ScalarTypeEnum.JSONObject(), isOptional: true },
+    implementationType: { type: ImplementationTypeEnum, isOptional: false },
+    implementationConfig: {
+      type: ScalarTypeEnum.JSONObject(),
+      isOptional: false,
+    },
+    maxInvocationsPerMinute: {
+      type: ScalarTypeEnum.Int_unsecure(),
+      isOptional: true,
+    },
+    timeoutMs: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true },
+    tags: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isArray: true,
+      isOptional: true,
+    },
+  },
+});
+
+export const UpdateToolInputModel = defineSchemaModel({
+  name: 'UpdateToolInput',
+  description: 'Input for updating a tool',
+  fields: {
+    toolId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    name: { type: ScalarTypeEnum.NonEmptyString(), isOptional: true },
+    description: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    status: { type: ToolStatusEnum, isOptional: true },
+    parametersSchema: { type: ScalarTypeEnum.JSONObject(), isOptional: true },
+    outputSchema: { type: ScalarTypeEnum.JSONObject(), isOptional: true },
+    implementationConfig: {
+      type: ScalarTypeEnum.JSONObject(),
+      isOptional: true,
+    },
+    maxInvocationsPerMinute: {
+      type: ScalarTypeEnum.Int_unsecure(),
+      isOptional: true,
+    },
+    timeoutMs: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true },
+    tags: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isArray: true,
+      isOptional: true,
+    },
+  },
+});
+
+// ============ Contracts ============
+
+/**
+ * CreateToolCommand - Creates a new tool definition
+ */
+export const CreateToolCommand = defineCommand({
+  meta: {
+    name: 'agent.tool.create',
+    version: 1,
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['tool', 'create'],
+    description: 'Creates a new AI tool definition.',
+    goal: 'Allow users to define new tools that agents can use.',
+    context: 'Called from the tool builder UI when creating a new tool.',
+  },
+  io: {
+    input: CreateToolInputModel,
+    output: defineSchemaModel({
+      name: 'CreateToolOutput',
+      fields: {
+        id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+        name: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+        slug: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+        status: { type: ToolStatusEnum, isOptional: false },
+      },
+    }),
+    errors: {
+      SLUG_EXISTS: {
+        description: 'A tool with this slug already exists in the organization',
+        http: 409,
+        gqlCode: 'SLUG_EXISTS',
+        when: 'Slug is already taken',
+      },
+    },
+  },
+  policy: {
+    auth: 'user',
+  },
+  sideEffects: {
+    emits: [
+      {
+        name: 'tool.created',
+        version: 1,
+        when: 'Tool is successfully created',
+        payload: ToolSummaryModel,
+      },
+    ],
+    audit: ['tool.created'],
+  },
+});
+
+/**
+ * UpdateToolCommand - Updates an existing tool
+ */
+export const UpdateToolCommand = defineCommand({
+  meta: {
+    name: 'agent.tool.update',
+    version: 1,
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['tool', 'update'],
+    description: 'Updates an existing AI tool definition.',
+    goal: 'Allow users to modify tool settings and configuration.',
+    context: 'Called from the tool settings UI.',
+  },
+  io: {
+    input: UpdateToolInputModel,
+    output: defineSchemaModel({
+      name: 'UpdateToolOutput',
+      fields: {
+        id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+        name: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+        status: { type: ToolStatusEnum, isOptional: false },
+        updatedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+      },
+    }),
+    errors: {
+      TOOL_NOT_FOUND: {
+        description: 'The specified tool does not exist',
+        http: 404,
+        gqlCode: 'TOOL_NOT_FOUND',
+        when: 'Tool ID is invalid',
+      },
+    },
+  },
+  policy: {
+    auth: 'user',
+  },
+  sideEffects: {
+    emits: [
+      {
+        name: 'tool.updated',
+        version: 1,
+        when: 'Tool is updated',
+        payload: ToolSummaryModel,
+      },
+    ],
+    audit: ['tool.updated'],
+  },
+});
+
+/**
+ * GetToolQuery - Retrieves a tool by ID
+ */
+export const GetToolQuery = defineQuery({
+  meta: {
+    name: 'agent.tool.get',
+    version: 1,
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['tool', 'get'],
+    description: 'Retrieves a tool by its ID.',
+    goal: 'View detailed tool configuration.',
+    context: 'Called when viewing tool details or editing.',
+  },
+  io: {
+    input: defineSchemaModel({
+      name: 'GetToolInput',
+      fields: {
+        toolId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+      },
+    }),
+    output: ToolModel,
+    errors: {
+      TOOL_NOT_FOUND: {
+        description: 'The specified tool does not exist',
+        http: 404,
+        gqlCode: 'TOOL_NOT_FOUND',
+        when: 'Tool ID is invalid',
+      },
+    },
+  },
+  policy: {
+    auth: 'user',
+  },
+});
+
+/**
+ * ListToolsQuery - Lists tools for an organization
+ */
+export const ListToolsQuery = defineQuery({
+  meta: {
+    name: 'agent.tool.list',
+    version: 1,
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['tool', 'list'],
+    description: 'Lists tools for an organization with optional filtering.',
+    goal: 'Browse and search available tools.',
+    context: 'Tool list/dashboard view.',
+  },
+  io: {
+    input: defineSchemaModel({
+      name: 'ListToolsInput',
+      fields: {
+        organizationId: {
+          type: ScalarTypeEnum.String_unsecure(),
+          isOptional: false,
+        },
+        category: { type: ToolCategoryEnum, isOptional: true },
+        status: { type: ToolStatusEnum, 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: 'ListToolsOutput',
+      fields: {
+        items: { type: ToolSummaryModel, isArray: true, isOptional: false },
+        total: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+        hasMore: { type: ScalarTypeEnum.Boolean(), isOptional: false },
+      },
+    }),
+  },
+  policy: {
+    auth: 'user',
+  },
+});
+
+/**
+ * TestToolCommand - Tests a tool with sample input
+ */
+export const TestToolCommand = defineCommand({
+  meta: {
+    name: 'agent.tool.test',
+    version: 1,
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['tool', 'test'],
+    description: 'Tests a tool with sample input to verify it works correctly.',
+    goal: 'Validate tool configuration before deployment.',
+    context: 'Tool builder UI - test panel.',
+  },
+  io: {
+    input: defineSchemaModel({
+      name: 'TestToolInput',
+      fields: {
+        toolId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+        testInput: { type: ScalarTypeEnum.JSONObject(), isOptional: false },
+      },
+    }),
+    output: defineSchemaModel({
+      name: 'TestToolOutput',
+      fields: {
+        success: { type: ScalarTypeEnum.Boolean(), isOptional: false },
+        output: { type: ScalarTypeEnum.JSONObject(), isOptional: true },
+        error: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+        durationMs: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+      },
+    }),
+    errors: {
+      TOOL_NOT_FOUND: {
+        description: 'The specified tool does not exist',
+        http: 404,
+        gqlCode: 'TOOL_NOT_FOUND',
+        when: 'Tool ID is invalid',
+      },
+      TOOL_EXECUTION_ERROR: {
+        description: 'Tool execution failed',
+        http: 500,
+        gqlCode: 'TOOL_EXECUTION_ERROR',
+        when: 'Tool returns an error',
+      },
+    },
+  },
+  policy: {
+    auth: 'user',
+  },
+  sideEffects: {
+    audit: ['tool.tested'],
+  },
+});

package/src/entities/agent.ts

@@ -0,0 +1,151 @@
+import {
+  defineEntity,
+  defineEntityEnum,
+  field,
+  index,
+} from '@lssm/lib.schema/entity';
+
+/**
+ * Agent status for lifecycle management
+ */
+export const AgentStatusEnum = defineEntityEnum({
+  name: 'AgentStatus',
+  values: [
+    'DRAFT', // Being configured
+    'ACTIVE', // Available for execution
+    'PAUSED', // Temporarily unavailable
+    'ARCHIVED', // No longer active
+  ],
+  description: 'Lifecycle status of the agent',
+});
+
+/**
+ * Agent model provider
+ */
+export const ModelProviderEnum = 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' }),
+    // Model configuration
+    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.',
+    }),
+    // Prompts
+    systemPrompt: field.string({ description: 'System prompt for the agent' }),
+    userPromptTemplate: field.string({
+      isOptional: true,
+      description: 'Template for user prompts',
+    }),
+    // Tool configuration
+    toolIds: field.string({
+      isArray: true,
+      isOptional: true,
+      description: 'IDs of assigned tools',
+    }),
+    toolChoice: field.string({
+      default: 'auto',
+      description: "Tool selection mode: 'auto', 'required', 'none'",
+    }),
+    // Execution limits
+    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',
+    }),
+    // Metadata
+    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',
+    }),
+    // Relations (virtual for type purposes)
+    tools: field.hasMany('Tool', {
+      description: 'Tools assigned to this agent',
+    }),
+  },
+  indexes: [
+    index.unique(['organizationId', 'slug']),
+    index.on(['organizationId', 'status']),
+    index.on(['modelProvider', 'modelName']),
+  ],
+  enums: [AgentStatusEnum, ModelProviderEnum],
+});
+
+/**
+ * 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' }),
+    // Tool-specific configuration for this agent
+    config: field.json({
+      isOptional: true,
+      description: 'Tool-specific configuration for this agent',
+    }),
+    // Ordering for tool priority
+    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(),
+    // Relations
+    agent: field.belongsTo('Agent', ['agentId'], ['id']),
+    tool: field.belongsTo('Tool', ['toolId'], ['id']),
+  },
+  indexes: [
+    index.unique(['agentId', 'toolId']),
+    index.on(['agentId', 'order']),
+  ],
+});

package/src/entities/index.ts

@@ -0,0 +1,20 @@
+// Tool entities
+export { ToolEntity, ToolCategoryEnum, ToolStatusEnum } from './tool';
+
+// Agent entities
+export {
+  AgentEntity,
+  AgentToolEntity,
+  AgentStatusEnum,
+  ModelProviderEnum,
+} from './agent';
+
+// Run entities
+export {
+  RunEntity,
+  RunStepEntity,
+  RunLogEntity,
+  RunStatusEnum,
+  RunStepTypeEnum,
+  LogLevelEnum,
+} from './run';

package/src/entities/log.ts

@@ -0,0 +1,76 @@
+import { defineEntity, defineEntityEnum, field, index } from '@lssm/lib.schema';
+
+/**
+ * Log level enum.
+ */
+export const LogLevelEnum = defineEntityEnum({
+  name: 'LogLevel',
+  values: ['DEBUG', 'INFO', 'WARN', 'ERROR'] as const,
+  schema: 'agent',
+  description: 'Log severity level.',
+});
+
+/**
+ * Log type enum.
+ */
+export const LogTypeEnum = defineEntityEnum({
+  name: 'LogType',
+  values: [
+    'MESSAGE',
+    'TOOL_CALL',
+    'TOOL_RESULT',
+    'THINKING',
+    'ERROR',
+    'SYSTEM',
+  ] as const,
+  schema: 'agent',
+  description: 'Type of log entry.',
+});
+
+/**
+ * RunLog entity - detailed run logs.
+ */
+export const RunLogEntity = defineEntity({
+  name: 'RunLog',
+  description: 'A log entry within an agent run.',
+  schema: 'agent',
+  map: 'run_log',
+  fields: {
+    id: field.id(),
+
+    // Parent
+    runId: field.foreignKey(),
+
+    // Type
+    type: field.enum('LogType'),
+    level: field.enum('LogLevel', { default: 'INFO' }),
+
+    // Content
+    role: field.string({
+      isOptional: true,
+      description: 'Message role (user, assistant, system, tool)',
+    }),
+    content: field.string({ description: 'Log content/message' }),
+
+    // Metadata
+    metadata: field.json({ isOptional: true }),
+
+    // Sequence
+    sequence: field.int({ description: 'Order within run' }),
+    iteration: field.int({ isOptional: true }),
+
+    // Tokens
+    tokens: field.int({ isOptional: true }),
+
+    // Timing
+    timestamp: field.dateTime(),
+    durationMs: field.int({ isOptional: true }),
+
+    // Relations
+    run: field.belongsTo('AgentRun', ['runId'], ['id'], {
+      onDelete: 'Cascade',
+    }),
+  },
+  indexes: [index.on(['runId', 'sequence']), index.on(['runId', 'type'])],
+  enums: [LogLevelEnum, LogTypeEnum],
+});