@elevasis/core 0.21.0 → 0.23.0

package/src/business/acquisition/build-templates.ts

@@ -1,28 +1,60 @@
-import { DEFAULT_ORGANIZATION_MODEL_PROSPECTING } from '../../organization-model/domains/prospecting'
-import type { BuildPlanSnapshot, BuildPlanSnapshotStep } from './types'
-
-export const PROSPECTING_BUILD_TEMPLATE_OPTIONS = DEFAULT_ORGANIZATION_MODEL_PROSPECTING.buildTemplates.map(
-  ({ id, label, description }) => ({
-    id,
-    label,
-    description
-  })
-)
-
-export const DEFAULT_PROSPECTING_BUILD_TEMPLATE_ID = DEFAULT_ORGANIZATION_MODEL_PROSPECTING.defaultBuildTemplateId
-
-export function isProspectingBuildTemplateId(value: string): boolean {
-  return PROSPECTING_BUILD_TEMPLATE_OPTIONS.some((template) => template.id === value)
-}
-
-export function createBuildPlanSnapshotFromTemplateId(templateId: string): BuildPlanSnapshot | null {
-  const template = DEFAULT_ORGANIZATION_MODEL_PROSPECTING.buildTemplates.find((item) => item.id === templateId)
-  if (!template) return null
-
-  return {
-    templateId: template.id,
-    templateLabel: template.label,
-    steps: template.steps.map((step): BuildPlanSnapshotStep => {
+// Phase 4: DEFAULT_ORGANIZATION_MODEL_PROSPECTING was deleted (compound domain removed per D8).
+// Build-template definitions are now sourced inline from PROSPECTING_STEPS, which retains
+// the step catalog. The template catalog (id, label, description, steps[]) is declared here
+// as a local constant — Wave 2 will author these as system.content entries on the canonical OM.
+import {
+  PROSPECTING_STEPS,
+  type CredentialRequirement,
+  type ListBuilderStep,
+  type RecordColumnConfig
+} from '../../organization-model/domains/prospecting'
+import type { BuildPlanSnapshot, BuildPlanSnapshotStep } from './types'
+
+interface BuildTemplateCatalogEntry {
+  id: string
+  label: string
+  description?: string
+  steps: ListBuilderStep[]
+}
+
+// Template catalog — mirrors the data that lived in DEFAULT_ORGANIZATION_MODEL_PROSPECTING.buildTemplates.
+// Wave 2 canonical OM will author these as (kind:'schema', type:'template') content nodes.
+const BUILD_TEMPLATE_CATALOG: BuildTemplateCatalogEntry[] = [
+  {
+    id: 'local-services',
+    label: 'Local Services',
+    description: 'Source, analyze, qualify, and personalize local service businesses for outreach.',
+    steps: Object.values(PROSPECTING_STEPS.localServices)
+  },
+  {
+    id: 'dtc-subscription-apollo-clickup',
+    label: 'DTC Subscription (Apollo + ClickUp)',
+    description:
+      'Import DTC brand leads from Apollo, crawl their websites, score fit, enrich contacts, and export via ClickUp.',
+    steps: Object.values(PROSPECTING_STEPS.dtcApolloClickup)
+  }
+]
+
+export const DEFAULT_PROSPECTING_BUILD_TEMPLATE_ID = 'local-services'
+
+export const PROSPECTING_BUILD_TEMPLATE_OPTIONS = BUILD_TEMPLATE_CATALOG.map(({ id, label, description }) => ({
+  id,
+  label,
+  description
+}))
+
+export function isProspectingBuildTemplateId(value: string): boolean {
+  return PROSPECTING_BUILD_TEMPLATE_OPTIONS.some((template) => template.id === value)
+}
+
+export function createBuildPlanSnapshotFromTemplateId(templateId: string): BuildPlanSnapshot | null {
+  const template = BUILD_TEMPLATE_CATALOG.find((item: BuildTemplateCatalogEntry) => item.id === templateId)
+  if (!template) return null
+
+  return {
+    templateId: template.id,
+    templateLabel: template.label,
+    steps: template.steps.map((step: ListBuilderStep): BuildPlanSnapshotStep => {
       const snapshotStep: BuildPlanSnapshotStep = {
         id: step.id,
         label: step.label,
@@ -32,7 +64,7 @@ export function createBuildPlanSnapshotFromTemplateId(templateId: string): Build
         recordsStageKey: step.recordsStageKey ?? step.stageKey,
         recordSourceStageKey: step.recordSourceStageKey ?? step.recordsStageKey ?? step.stageKey,
         dependencyMode: step.dependencyMode,
-        capabilityKey: step.capabilityKey,
+        actionKey: step.actionKey,
         defaultBatchSize: step.defaultBatchSize,
         maxBatchSize: step.maxBatchSize
       }
@@ -41,16 +73,26 @@ export function createBuildPlanSnapshotFromTemplateId(templateId: string): Build
       if (step.recordEntity) snapshotStep.recordEntity = step.recordEntity
       if (step.dependsOn?.length) snapshotStep.dependsOn = [...step.dependsOn]
       if (step.credentialRequirements?.length) {
-        snapshotStep.credentialRequirements = step.credentialRequirements.map((requirement) => ({ ...requirement }))
+        snapshotStep.credentialRequirements = step.credentialRequirements.map((requirement: CredentialRequirement) => ({
+          ...requirement
+        }))
       }
       if (step.recordColumns) {
         snapshotStep.recordColumns = {
-          ...(step.recordColumns.company ? { company: step.recordColumns.company.map((column) => ({ ...column })) } : {}),
-          ...(step.recordColumns.contact ? { contact: step.recordColumns.contact.map((column) => ({ ...column })) } : {})
+          ...(step.recordColumns.company
+            ? {
+                company: step.recordColumns.company.map((column: RecordColumnConfig) => ({ ...column }))
+              }
+            : {}),
+          ...(step.recordColumns.contact
+            ? {
+                contact: step.recordColumns.contact.map((column: RecordColumnConfig) => ({ ...column }))
+              }
+            : {})
         }
       }
 
       return snapshotStep
     })
   }
-}
+}

package/src/business/acquisition/crm-state-actions.test.ts

@@ -1,5 +1,8 @@
 import { describe, expect, it } from 'vitest'
-import { DEFAULT_ORGANIZATION_MODEL_SALES, LEAD_GEN_PIPELINE_DEFINITIONS } from '../../organization-model/domains/sales'
+// Phase 4 (D8): DEFAULT_ORGANIZATION_MODEL_SALES no longer exported — pipeline data moved to
+// system.content. CRM_PIPELINE_DEFINITION is retained as the Stateful pipeline shape
+// for CRM business logic (separate from the OM content nodes).
+import { CRM_PIPELINE_DEFINITION, LEAD_GEN_PIPELINE_DEFINITIONS } from '../../organization-model/domains/sales'
 import { ActivityEventSchema } from './activity-events'
 import { DealStageSchema, TransitionItemRequestSchema } from './api-schemas'
 import { deriveActions } from './derive-actions'
@@ -106,15 +109,14 @@ describe('ActivityEventSchema', () => {
 })
 
 describe('CRM stage and transition vocabulary contracts', () => {
-  it('keeps DealStage, DealStageSchema, and the default sales pipeline stages aligned', () => {
-    const defaultPipeline = DEFAULT_ORGANIZATION_MODEL_SALES.pipelines.find(
-      (pipeline) => pipeline.id === DEFAULT_ORGANIZATION_MODEL_SALES.defaultPipelineId
-    )
-    const defaultSalesStages = defaultPipeline?.stages
-      .toSorted((left, right) => left.order - right.order)
-      .map((stage) => stage.id)
-
-    expect(defaultSalesStages).toEqual([...DEAL_STAGES])
+  // Phase 4 (D8): DEFAULT_ORGANIZATION_MODEL_SALES.pipelines removed.
+  // CRM_PIPELINE_DEFINITION (StatefulPipelineDefinition) is the retained Stateful-trait
+  // pipeline shape used by CRM business logic. stageKey → DealStageSchema alignment
+  // is now verified against CRM_PIPELINE_DEFINITION.stages[*].stageKey.
+  it('keeps DealStage, DealStageSchema, and CRM_PIPELINE_DEFINITION stages aligned', () => {
+    const crmStageKeys = CRM_PIPELINE_DEFINITION.stages.map((stage) => stage.stageKey)
+
+    expect(crmStageKeys).toEqual([...DEAL_STAGES])
     expect(DealStageSchema.options).toEqual([...DEAL_STAGES])
   })
 
@@ -122,7 +124,7 @@ describe('CRM stage and transition vocabulary contracts', () => {
     for (const stageKey of DEAL_STAGES) {
       expect(
         TransitionItemRequestSchema.safeParse({
-          pipelineKey: DEFAULT_ORGANIZATION_MODEL_SALES.defaultPipelineId,
+          pipelineKey: CRM_PIPELINE_DEFINITION.pipelineKey,
           stageKey,
           stateKey: null,
           expectedUpdatedAt: '2026-04-27T12:34:56.000Z'

package/src/business/acquisition/index.ts

@@ -61,6 +61,8 @@ export {
   ListStageCountsSchema,
   ListTelemetrySchema,
   ListIdParamsSchema,
+  ListReadQuerySchema,
+  GetListQuerySchema,
   CreateListRequestSchema,
   UpdateListRequestSchema,
   UpdateListStatusRequestSchema,
@@ -70,7 +72,11 @@ export {
   AddContactsToListRequestSchema,
   RecordListExecutionRequestSchema,
   AcqListResponseSchema,
+  AcqListDetailResponseSchema,
   AcqListListResponseSchema,
+  AcqListDealRefSchema,
+  AcqListLineageSchema,
+  AcqListStatusResponseSchema,
   ListTelemetryResponseSchema,
   ListTelemetryListResponseSchema,
   ListExecutionSummarySchema,
@@ -144,6 +150,8 @@ export {
   type ListStageCountsInput,
   type ListTelemetryInput,
   type ListIdParams,
+  type ListReadQuery,
+  type GetListQuery,
   type CreateListRequest,
   type UpdateListRequest,
   type UpdateListStatusRequest,
@@ -153,7 +161,11 @@ export {
   type AddContactsToListRequest,
   type RecordListExecutionRequest,
   type AcqListResponse,
+  type AcqListDetailResponse,
   type AcqListListResponse,
+  type AcqListDealRef,
+  type AcqListLineage,
+  type AcqListStatusResponse,
   type ListTelemetryResponse,
   type ListTelemetryListResponse,
   type ListExecutionSummaryInput,

package/src/business/acquisition/types.ts

@@ -1,5 +1,9 @@
 import type { Database } from '../../supabase/database.types'
-import type { Capability, CredentialRequirement, RecordColumnConfig } from '../../organization-model/domains/prospecting'
+import type {
+  ActionRegistry,
+  CredentialRequirement,
+  RecordColumnConfig
+} from '../../organization-model/domains/prospecting'
 import type { LEAD_GEN_STAGE_CATALOG } from '../../organization-model/domains/sales'
 import type { PipelineStage, ProcessingStageStatus } from './api-schemas'
 
@@ -52,7 +56,7 @@ export interface WebPost {
 }
 
 export type LeadGenStageKey = (typeof LEAD_GEN_STAGE_CATALOG)[keyof typeof LEAD_GEN_STAGE_CATALOG]['key']
-export type LeadGenCapabilityKey = Capability['id']
+export type LeadGenActionKey = ActionRegistry[number]['id']
 
 export interface ProcessingStateEntry {
   status: ProcessingStageStatus
@@ -172,7 +176,7 @@ export interface BuildPlanSnapshotStep {
   recordSourceStageKey?: string
   dependsOn?: string[]
   dependencyMode: BuildPlanSnapshotDependencyMode
-  capabilityKey: string
+  actionKey: string
   defaultBatchSize: number
   maxBatchSize: number
   recordColumns?: Partial<Record<BuildPlanSnapshotPrimaryEntity, RecordColumnConfig[]>>

package/src/business/clients/api-schemas.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, it } from 'vitest'
+import {
+  ClientDetailResponseSchema,
+  ClientListResponseSchema,
+  ClientStatusResponseSchema,
+  ListClientsQuerySchema
+} from './api-schemas'
+
+const VALID_UUID = '00000000-0000-4000-8000-000000000001'
+const ISO_TS = '2026-05-08T00:00:00.000Z'
+
+describe('client API schemas', () => {
+  it('coerces list pagination and accepts status/search filters', () => {
+    const result = ListClientsQuerySchema.safeParse({
+      status: 'active',
+      search: 'Acme',
+      limit: '10',
+      offset: '20'
+    })
+
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data).toEqual({
+        status: 'active',
+        search: 'Acme',
+        limit: 10,
+        offset: 20
+      })
+    }
+  })
+
+  it('rejects unknown list query fields', () => {
+    expect(ListClientsQuerySchema.safeParse({ includeDeals: true }).success).toBe(false)
+  })
+
+  it('accepts client list responses', () => {
+    expect(
+      ClientListResponseSchema.safeParse({
+        data: [
+          {
+            id: VALID_UUID,
+            organizationId: VALID_UUID,
+            name: 'Acme',
+            status: 'active',
+            sourceDealId: null,
+            primaryCompanyId: null,
+            primaryContactId: null,
+            convertedAt: null,
+            metadata: {},
+            createdAt: ISO_TS,
+            updatedAt: ISO_TS
+          }
+        ],
+        total: 1,
+        limit: 50,
+        offset: 0
+      }).success
+    ).toBe(true)
+  })
+
+  it('accepts client detail lineage refs', () => {
+    expect(
+      ClientDetailResponseSchema.safeParse({
+        id: VALID_UUID,
+        organizationId: VALID_UUID,
+        name: 'Acme',
+        status: 'onboarding',
+        sourceDealId: VALID_UUID,
+        primaryCompanyId: VALID_UUID,
+        primaryContactId: VALID_UUID,
+        convertedAt: ISO_TS,
+        metadata: { source: 'closed_won' },
+        createdAt: ISO_TS,
+        updatedAt: ISO_TS,
+        lineage: {
+          deals: [
+            {
+              id: VALID_UUID,
+              contactEmail: 'lead@example.com',
+              stageKey: 'closed_won',
+              stateKey: null,
+              updatedAt: ISO_TS
+            }
+          ],
+          projects: [{ id: VALID_UUID, name: 'Delivery', kind: 'client_engagement', status: 'active', updatedAt: ISO_TS }],
+          companies: [{ id: VALID_UUID, name: 'Acme Co', domain: 'acme.test', status: 'active' }],
+          contacts: [
+            {
+              id: VALID_UUID,
+              email: 'lead@example.com',
+              firstName: 'Ada',
+              lastName: null,
+              title: 'CEO',
+              companyId: VALID_UUID,
+              status: 'active'
+            }
+          ]
+        }
+      }).success
+    ).toBe(true)
+  })
+
+  it('accepts client portfolio status responses', () => {
+    expect(
+      ClientStatusResponseSchema.safeParse({
+        totalClients: 1,
+        byStatus: { active: 1, onboarding: 0, paused: 0, completed: 0, churned: 0 },
+        linkedDeals: 1,
+        linkedProjects: 1,
+        linkedCompanies: 1,
+        linkedContacts: 1
+      }).success
+    ).toBe(true)
+  })
+})

package/src/business/clients/api-schemas.ts

@@ -0,0 +1,158 @@
+import { z } from 'zod'
+import { UuidSchema } from '../../platform/utils/validation'
+
+export const ClientStatusSchema = z.enum(['active', 'onboarding', 'paused', 'completed', 'churned'])
+
+export const ClientIdParamsSchema = z
+  .object({
+    clientId: UuidSchema
+  })
+  .strict()
+
+export const ListClientsQuerySchema = z
+  .object({
+    status: ClientStatusSchema.optional(),
+    search: z.string().trim().min(1).max(255).optional(),
+    limit: z.coerce.number().int().min(1).max(100).default(50),
+    offset: z.coerce.number().int().min(0).default(0)
+  })
+  .strict()
+
+export const ClientRefSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  status: ClientStatusSchema
+})
+
+export const ClientResponseSchema = z.object({
+  id: z.string(),
+  organizationId: z.string(),
+  name: z.string(),
+  status: ClientStatusSchema,
+  sourceDealId: z.string().nullable(),
+  primaryCompanyId: z.string().nullable(),
+  primaryContactId: z.string().nullable(),
+  convertedAt: z.string().nullable(),
+  metadata: z.record(z.string(), z.unknown()),
+  createdAt: z.string(),
+  updatedAt: z.string()
+})
+
+export const ClientDealRefSchema = z.object({
+  id: z.string(),
+  contactEmail: z.string(),
+  stageKey: z.string().nullable(),
+  stateKey: z.string().nullable(),
+  updatedAt: z.string()
+})
+
+export const ClientProjectRefSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  kind: z.string(),
+  status: z.string(),
+  updatedAt: z.string()
+})
+
+export const ClientCompanyRefSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  domain: z.string().nullable(),
+  status: z.string()
+})
+
+export const ClientContactRefSchema = z.object({
+  id: z.string(),
+  email: z.string(),
+  firstName: z.string().nullable(),
+  lastName: z.string().nullable(),
+  title: z.string().nullable(),
+  companyId: z.string().nullable(),
+  status: z.string()
+})
+
+export const ClientLineageSchema = z.object({
+  deals: z.array(ClientDealRefSchema),
+  projects: z.array(ClientProjectRefSchema),
+  companies: z.array(ClientCompanyRefSchema),
+  contacts: z.array(ClientContactRefSchema)
+})
+
+export const ClientDetailResponseSchema = ClientResponseSchema.extend({
+  lineage: ClientLineageSchema
+})
+
+export const ClientListResponseSchema = z.object({
+  data: z.array(ClientResponseSchema),
+  total: z.number().int().min(0),
+  limit: z.number().int().min(1),
+  offset: z.number().int().min(0)
+})
+
+export const ClientStatusResponseSchema = z.object({
+  totalClients: z.number().int().min(0),
+  byStatus: z.record(ClientStatusSchema, z.number().int().min(0)),
+  linkedDeals: z.number().int().min(0),
+  linkedProjects: z.number().int().min(0),
+  linkedCompanies: z.number().int().min(0),
+  linkedContacts: z.number().int().min(0)
+})
+
+export const CreateClientRequestSchema = z
+  .object({
+    name: z.string().trim().min(1).max(255),
+    status: ClientStatusSchema.optional(),
+    sourceDealId: UuidSchema.nullable().optional(),
+    primaryCompanyId: UuidSchema.nullable().optional(),
+    primaryContactId: UuidSchema.nullable().optional(),
+    metadata: z.record(z.string(), z.unknown()).nullable().optional()
+  })
+  .strict()
+
+export const UpdateClientRequestSchema = z
+  .object({
+    name: z.string().trim().min(1).max(255).optional(),
+    status: ClientStatusSchema.optional(),
+    sourceDealId: UuidSchema.nullable().optional(),
+    primaryCompanyId: UuidSchema.nullable().optional(),
+    primaryContactId: UuidSchema.nullable().optional(),
+    metadata: z.record(z.string(), z.unknown()).nullable().optional()
+  })
+  .strict()
+  .refine((data) => Object.keys(data).length > 0, {
+    message: 'At least one field must be provided'
+  })
+
+export const ClientSchemas = {
+  ClientStatus: ClientStatusSchema,
+  ClientIdParams: ClientIdParamsSchema,
+  ListClientsQuery: ListClientsQuerySchema,
+  ClientRef: ClientRefSchema,
+  ClientResponse: ClientResponseSchema,
+  ClientDealRef: ClientDealRefSchema,
+  ClientProjectRef: ClientProjectRefSchema,
+  ClientCompanyRef: ClientCompanyRefSchema,
+  ClientContactRef: ClientContactRefSchema,
+  ClientLineage: ClientLineageSchema,
+  ClientDetailResponse: ClientDetailResponseSchema,
+  ClientListResponse: ClientListResponseSchema,
+  ClientStatusResponse: ClientStatusResponseSchema,
+  CreateClientRequest: CreateClientRequestSchema,
+  UpdateClientRequest: UpdateClientRequestSchema
+}
+
+export type ClientStatus = z.infer<typeof ClientStatusSchema>
+export type ClientIdParams = z.infer<typeof ClientIdParamsSchema>
+export type ListClientsQuery = z.infer<typeof ListClientsQuerySchema>
+export type ClientRef = z.infer<typeof ClientRefSchema>
+export type ClientResponse = z.infer<typeof ClientResponseSchema>
+export type ClientDealRef = z.infer<typeof ClientDealRefSchema>
+export type ClientProjectRef = z.infer<typeof ClientProjectRefSchema>
+export type ClientCompanyRef = z.infer<typeof ClientCompanyRefSchema>
+export type ClientContactRef = z.infer<typeof ClientContactRefSchema>
+export type ClientLineage = z.infer<typeof ClientLineageSchema>
+export type ClientDetailResponse = z.infer<typeof ClientDetailResponseSchema>
+export type ClientListResponse = z.infer<typeof ClientListResponseSchema>
+export type ClientStatusResponse = z.infer<typeof ClientStatusResponseSchema>
+export type CreateClientRequest = z.infer<typeof CreateClientRequestSchema>
+export type UpdateClientRequest = z.infer<typeof UpdateClientRequestSchema>

package/src/business/clients/index.ts

@@ -0,0 +1 @@
+export * from './api-schemas'

package/src/business/deals/api-schemas.ts

@@ -42,6 +42,10 @@ export {
   DealLookupResponseSchema,
   ConversationMessageSchema,
   DealConversationSchema,
+  DealLineageListRefSchema,
+  DealLineageProjectRefSchema,
+  DealLineageClientRefSchema,
+  DealLineageSchema,
   DealDetailResponseSchema,
   DealNoteResponseSchema,
   DealNoteListResponseSchema,
@@ -71,6 +75,10 @@ export {
   type DealLookupItem,
   type DealLookupResponse,
   type ConversationMessage,
+  type DealLineageListRef,
+  type DealLineageProjectRef,
+  type DealLineageClientRef,
+  type DealLineage,
   type DealDetailResponse,
   type DealNoteResponse,
   type DealNoteListResponse,

package/src/business/index.ts

@@ -5,8 +5,11 @@
  * Note: PDF has its own subpath exports (./pdf, ./pdf/browser, ./pdf/server, ./pdf/sections)
  */
 
-// Acquisition types (lead database domain types)
-export * from './acquisition/index'
+// Acquisition types (lead database domain types)
+export * from './acquisition/index'
+
+// Client hub schemas
+export * from './clients/index'
 
 // SEO types (seo_pages, seo_metrics, chart types)
 export * from './seo/index'

package/src/business/projects/types.ts

@@ -75,6 +75,24 @@ export interface ProjectDetail extends ProjectRow {
   milestones: MilestoneRow[]
   tasks: TaskRow[]
   company: { id: string; name: string; domain: string | null } | null
+  deal: ProjectSourceDealRef | null
+  client: ProjectClientRef | null
+}
+
+export interface ProjectSourceDealRef {
+  id: string
+  clientId?: string | null
+  contactEmail: string
+  stageKey: string | null
+  stateKey: string | null
+  sourceListId: string | null
+  updatedAt: string
+}
+
+export interface ProjectClientRef {
+  id: string
+  name: string
+  status: string
 }
 
 export interface MilestoneWithTasks extends MilestoneRow {
@@ -104,6 +122,7 @@ export interface Project {
   status: ProjectStatus
   description: string | null
   dealId: string | null
+  clientId: string | null
   clientCompanyId: string | null
   startDate: string | null
   targetEndDate: string | null

package/src/execution/engine/__tests__/fixtures/test-agents.ts

@@ -11,10 +11,11 @@ export function createPlatformToolAgent(): AgentDefinition {
     config: {
       resourceId: 'platform-tool-agent',
       name: 'Platform Tool Agent',
-      description: 'Test agent with platform tools for approval workflows',
-      systemPrompt: 'You help with approvals and notifications',
-      type: 'agent',
-      status: 'dev',
+      description: 'Test agent with platform tools for approval workflows',
+      systemPrompt: 'You help with approvals and notifications',
+      type: 'agent',
+      kind: 'utility',
+      status: 'dev',
       version: '1.0.0'
     },
     contract: {
@@ -68,10 +69,11 @@ export function createKnowledgeMapAgent(): AgentDefinition {
     config: {
       resourceId: 'knowledge-agent',
       name: 'Knowledge Map Agent',
-      description: 'Test agent with knowledge map for dynamic capability loading',
-      systemPrompt: 'You can load knowledge nodes as needed',
-      type: 'agent',
-      status: 'dev',
+      description: 'Test agent with knowledge map for dynamic capability loading',
+      systemPrompt: 'You can load knowledge nodes as needed',
+      type: 'agent',
+      kind: 'utility',
+      status: 'dev',
       version: '1.0.0'
     },
     contract: {

package/src/execution/engine/agent/core/__tests__/agent.test.ts

@@ -19,9 +19,10 @@ describe('Agent Execution', () => {
 
   // Helper: Create minimal agent definition with mock provider
   const createAgentDefinition = (overrides?: Partial<AgentDefinition>): AgentDefinition => {
-    const config: AgentConfig = {
-      type: 'agent',
-      resourceId: 'test-agent',
+    const config: AgentConfig = {
+      type: 'agent',
+      kind: 'utility',
+      resourceId: 'test-agent',
       name: 'Test Agent',
       description: 'Agent for testing',
       environment: 'dev',
@@ -165,9 +166,10 @@ describe('Agent Execution', () => {
 
     it('respects maxIterations constraint', async () => {
       const definition = createAgentDefinition({
-        config: {
-          type: 'agent',
-          resourceId: 'test-agent',
+        config: {
+          type: 'agent',
+          kind: 'utility',
+          resourceId: 'test-agent',
           name: 'Test Agent',
           description: 'Agent for testing',
           environment: 'dev',
@@ -418,9 +420,10 @@ describe('Agent Execution', () => {
 
     it('handles maxIterations edge case (zero iterations)', async () => {
       const definition = createAgentDefinition({
-        config: {
-          type: 'agent',
-          resourceId: 'test-agent',
+        config: {
+          type: 'agent',
+          kind: 'utility',
+          resourceId: 'test-agent',
           name: 'Test Agent',
           description: 'Agent for testing',
           environment: 'dev',
@@ -442,9 +445,10 @@ describe('Agent Execution', () => {
 
     it('handles negative maxIterations', async () => {
       const definition = createAgentDefinition({
-        config: {
-          type: 'agent',
-          resourceId: 'test-agent',
+        config: {
+          type: 'agent',
+          kind: 'utility',
+          resourceId: 'test-agent',
           name: 'Test Agent',
           description: 'Agent for testing',
           environment: 'dev',