Agent | dimensions-ai

classdesc

The agent is what participates in a match and contains details on the files powering the agent, the process associated and many other details.

Reads in a file source for the code and copies the bot folder to a temporary directory in secure modes and creates an Agent for use in the MatchEngine and Match

This is a class that should not be broken. If something goes wrong, this should always throw a error. It is expected that agents are used knowing beforehand that the file given is validated

Hierarchy

EventEmitter
- Agent

Index

Enumerations

Interfaces

Type aliases

Constructors

constructor

Methods

Object literals

Type aliases

Static GenerationMetaData

GenerationMetaData: GenerationMetaData_CreateMatch | GenerationMetaData_FilesOnly | GenerationMetaData_Tournament

Static GenerationMetaData_CreateMatch

GenerationMetaData_CreateMatch: Array<{ botkey?: string; file: string; name: string }>

Agent generation meta data used by Dimension.createMatch

Static GenerationMetaData_FilesOnly

GenerationMetaData_FilesOnly: Array<string>

Agent Generation meta data with paths to files only

Static GenerationMetaData_Tournament

GenerationMetaData_Tournament: Array<{ botkey?: string; file: string; tournamentID: ID; version: number }>

Agent generation meta data used by tournaments

Static ID

ID: number

Agent ID. Always a non-negative integer and all agents in a match have IDs that are strictly increasing from 0

For example, in a 4 agent match, the ids are 0, 1, 2, 3.

Static LanguageSpecificOptions

LanguageSpecificOptions: {}

Language specic options mapping programming language to the agent options to use for that programing language. Used to customize options such as docker image, compile time limits etc. on a per language basis

Type declaration

Constructors

constructor

new Agent(file: string, options: Partial<Options>, languageSpecificOptions?: LanguageSpecificOptions): Agent

- Defined in https://github.com/StoneT2000/Dimensions/blob/master/src/Agent/index.ts#L167
Parameters
- file: string
- options: Partial<Options>
- Default value languageSpecificOptions: LanguageSpecificOptions = {}
Returns Agent

Properties

_buffer

_buffer: Array<string> = []

internal buffer to store stdout from an agent that has yet to be delimited / used

_clearTimer

_clearTimer: Function = noop

Clears out the timer associated with the agent during a match

_currentMovePromise

_currentMovePromise: Promise<void>

a promise that resolves when the Agent's current move in the Match is finished

_currentMoveReject

_currentMoveReject: Function

_currentMoveResolve

_currentMoveResolve: Function = noop

_logsize

_logsize: number = 0

Size of agent's logs so far

_trimmed

_trimmed: boolean = false

agentTimeStep

agentTimeStep: number = 0

A number that counts the number of times the agent has essentially interacted with the MatchEngine

Private allowedToSendCommands

allowedToSendCommands: boolean = true

whether agent is allowed to send commands. Used to help ignore extra output from agents

cmd

cmd: string = null

The command used to run the file

Private container

container: Container = null

Associated docker container running the agent

creationDate

creationDate: Date

Creation date of the agent

currentMoveCommands

currentMoveCommands: Array<string> = []

The commands collected so far for the current move

cwd

cwd: string

The current working directory of the source file. If in insecure mode, this is always a temporary directory that will get deleted later.

errorLogWriteStream

errorLogWriteStream: WriteStream = null

ext

ext: string

The extension of the file

file

file: string

The original file path provided

id

id: ID = 0

This agent's ID in a match. It is always a non-negative integer and agents in a match are always numbered 0, 1, 2, ...n where there are n agents.

Private log

log: Logger = new Logger()

logkey

logkey: string = null

Key used to retrieve the error logs of this agent

memoryWatchInterval

memoryWatchInterval: any = null

Interval that periodically watches the memory usage of the process associated with this agent

messages

messages: Array<string> = []

List of all messages written to this agent are directly pushed to here when in detached mode

name

name: string

Name of the agent

default: agent_[agent.id]

options

options: Options = deepCopy(Agent.OptionDefaults)

The agent's options

Private process

process: ChildProcess = null

The associated process running the Agent

src

src: string

The source path to the file that runs the agent

srcNoExt

srcNoExt: string

file without extension

status

status: Status = Agent.Status.UNINITIALIZED

Current status of the agent

tournamentID

tournamentID: ID = null

A tournmanet ID if Agent is generated from within a {@link Tournament}

version

version: number = 0

Agent version, used by tournament

Static defaultMaxListeners

defaultMaxListeners: number

Methods

_allowCommands

_allowCommands(): void

- Defined in https://github.com/StoneT2000/Dimensions/blob/master/src/Agent/index.ts#L831
Allow agent to send commands again

Returns void

_compile

_compile(stderrWritestream: Writable, stdoutWritestream: Writable, engineOptions: EngineOptions): Promise<void>

- Defined in https://github.com/StoneT2000/Dimensions/blob/master/src/Agent/index.ts#L400
Compile whatever is needed and validate files. Called by MatchEngine and has a timer set by the maxCompileTime option in Agent.Options

Parameters
- stderrWritestream: Writable
- stdoutWritestream: Writable
- engineOptions: EngineOptions
Returns Promise<void>

_disallowCommands

_disallowCommands(): void

- Defined in https://github.com/StoneT2000/Dimensions/blob/master/src/Agent/index.ts#L824
Disallow an agent from sending more commands

Returns void

_finishMove

_finishMove(): Promise<void>

- Defined in https://github.com/StoneT2000/Dimensions/blob/master/src/Agent/index.ts#L857
Stop this agent from more outputs and mark it as done for now and awaiting for updates. Effectively force agent to sync with match

Returns Promise<void>

_getProcess

_getProcess(): ChildProcess

- Defined in https://github.com/StoneT2000/Dimensions/blob/master/src/Agent/index.ts#L747
Get process of agent

Returns ChildProcess

_install

_install(stderrWritestream: Writable, stdoutWritestream: Writable, engineOptions: EngineOptions): Promise<void>

- Defined in https://github.com/StoneT2000/Dimensions/blob/master/src/Agent/index.ts#L292
Install whatever is needed through a install.sh file in the root of the bot folder

Parameters
- stderrWritestream: Writable
- stdoutWritestream: Writable
- engineOptions: EngineOptions
Returns Promise<void>

_setTimeout

_setTimeout(fn: Function, delay: number, ...args: any[]): void

- Defined in https://github.com/StoneT2000/Dimensions/blob/master/src/Agent/index.ts#L845
Setup the agent timer clear out method

Parameters
- fn: Function
- delay: number
- Rest ...args: any[]
Returns void

_setupMemoryWatcher

_setupMemoryWatcher(engineOptions: EngineOptions): void

- Defined in https://github.com/StoneT2000/Dimensions/blob/master/src/Agent/index.ts#L891
Used by MatchEngine only. Setups the memory watcher if docker is not used.

Parameters
- engineOptions: EngineOptions
  
  engine options to configure the agent with
Returns void

_setupMove

_setupMove(): void

- Defined in https://github.com/StoneT2000/Dimensions/blob/master/src/Agent/index.ts#L876
Returns void

_spawn

_spawn(): Promise<ChildProcess | ContainerExecData>

- Defined in https://github.com/StoneT2000/Dimensions/blob/master/src/Agent/index.ts#L593
Spawn the process and return the process

Returns Promise<ChildProcess | ContainerExecData>

_spawnCompileProcess

_spawnCompileProcess(command: string, args: Array<string>): Promise<ChildProcess | ContainerExecData>

- Defined in https://github.com/StoneT2000/Dimensions/blob/master/src/Agent/index.ts#L538
Spawns the compilation process

Parameters
- command: string
  
  command to compile with
- args: Array<string>
  
  argument for the compilation
Returns Promise<ChildProcess | ContainerExecData>

_spawnProcess

_spawnProcess(command: string, args: Array<string>): Promise<ChildProcess | ContainerExecData>

- Defined in https://github.com/StoneT2000/Dimensions/blob/master/src/Agent/index.ts#L630
Spawns process in this.cwd accordingly and uses the configs accordingly. Resolves with the process if spawned succesfully

Note, we are spawning detached so we can kill off all sub processes if they are made. See _terminate for explanation

Parameters
- command: string
- args: Array<string>
Returns Promise<ChildProcess | ContainerExecData>

_storeProcess

_storeProcess(p: ChildProcess): void

- Defined in https://github.com/StoneT2000/Dimensions/blob/master/src/Agent/index.ts#L755
Store process for agent

Parameters
- p: ChildProcess
  
  process to store
Returns void

_terminate

_terminate(): Promise<void>

- Defined in https://github.com/StoneT2000/Dimensions/blob/master/src/Agent/index.ts#L770
Terminates this agent by stopping all related processes and remove any temporary directory. this is the only function allowed to set the status value to killed.

Returns Promise<void>

addListener

addListener(event: string | symbol, listener: (...args: any[]) => void): this

Inherited from Ladder.addListener

Overrides EventEmitter.addListener
Parameters
- event: string | symbol
- listener: (...args: any[]) => void
  - - (...args: any[]): void
    - Parameters
      - Rest ...args: any[]
      Returns void
Returns this

containerSpawn

containerSpawn(command: string, workingDir?: string): Promise<ContainerExecData>

- Defined in https://github.com/StoneT2000/Dimensions/blob/master/src/Agent/index.ts#L562
Executes the given command string in the agent's container and attaches stdin, stdout, and stderr accordingly

Parameters
- command: string
  
  the command to execute in the container
- Default value workingDir: string = "/"
Returns Promise<ContainerExecData>

emit

emit(event: string | symbol, ...args: any[]): boolean

Inherited from Ladder.emit

Overrides EventEmitter.emit
Parameters
- event: string | symbol
- Rest ...args: any[]
Returns boolean

eventNames

eventNames(): Array<string | symbol>

Inherited from Ladder.eventNames

Overrides EventEmitter.eventNames
Returns Array<string | symbol>

getAgentErrorLogFilename

getAgentErrorLogFilename(): string

- Defined in https://github.com/StoneT2000/Dimensions/blob/master/src/Agent/index.ts#L990
Returns string

getMaxListeners

getMaxListeners(): number

Inherited from Ladder.getMaxListeners

Overrides EventEmitter.getMaxListeners
Returns number

inputDestroyed

inputDestroyed(): boolean

- Defined in https://github.com/StoneT2000/Dimensions/blob/master/src/Agent/index.ts#L705
Whether or not input is destroyed

Returns boolean

isAllowedToSendCommands

isAllowedToSendCommands(): boolean

- Defined in https://github.com/StoneT2000/Dimensions/blob/master/src/Agent/index.ts#L838
Check if agent is set to be allowed to send commands. The EngineOptions affect when this is flipped

Returns boolean

isTerminated

isTerminated(): boolean

- Defined in https://github.com/StoneT2000/Dimensions/blob/master/src/Agent/index.ts#L762
Returns true if this agent was terminated and no longer send or receive emssages

Returns boolean

listenerCount

listenerCount(type: string | symbol): number

Inherited from Ladder.listenerCount

Overrides EventEmitter.listenerCount
Parameters
- type: string | symbol
Returns number

listeners

listeners(event: string | symbol): Function[]

Inherited from Ladder.listeners

Overrides EventEmitter.listeners
Parameters
- event: string | symbol
Returns Function[]

off

off(event: string | symbol, listener: (...args: any[]) => void): this

Inherited from Ladder.off

Overrides EventEmitter.off
Parameters
- event: string | symbol
- listener: (...args: any[]) => void
  - - (...args: any[]): void
    - Parameters
      - Rest ...args: any[]
      Returns void
Returns this

on

on(event: string | symbol, listener: (...args: any[]) => void): this

Inherited from Ladder.on

Overrides EventEmitter.on
Parameters
- event: string | symbol
- listener: (...args: any[]) => void
  - - (...args: any[]): void
    - Parameters
      - Rest ...args: any[]
      Returns void
Returns this

once

once(event: string | symbol, listener: (...args: any[]) => void): this

Inherited from Ladder.once

Overrides EventEmitter.once
Parameters
- event: string | symbol
- listener: (...args: any[]) => void
  - - (...args: any[]): void
    - Parameters
      - Rest ...args: any[]
      Returns void
Returns this

overMemory

overMemory(): void

- Defined in https://github.com/StoneT2000/Dimensions/blob/master/src/Agent/index.ts#L696
call out agent for exceeding memory limit

Returns void

prependListener

prependListener(event: string | symbol, listener: (...args: any[]) => void): this

Inherited from Ladder.prependListener

Overrides EventEmitter.prependListener
Parameters
- event: string | symbol
- listener: (...args: any[]) => void
  - - (...args: any[]): void
    - Parameters
      - Rest ...args: any[]
      Returns void
Returns this

prependOnceListener

prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this

Inherited from Ladder.prependOnceListener

Overrides EventEmitter.prependOnceListener
Parameters
- event: string | symbol
- listener: (...args: any[]) => void
  - - (...args: any[]): void
    - Parameters
      - Rest ...args: any[]
      Returns void
Returns this

rawListeners

rawListeners(event: string | symbol): Function[]

Inherited from Ladder.rawListeners

Overrides EventEmitter.rawListeners
Parameters
- event: string | symbol
Returns Function[]

removeAllListeners

removeAllListeners(event?: string | symbol): this

Inherited from Ladder.removeAllListeners

Overrides EventEmitter.removeAllListeners
Parameters
- Optional event: string | symbol
Returns this

removeListener

removeListener(event: string | symbol, listener: (...args: any[]) => void): this

Inherited from Ladder.removeListener

Overrides EventEmitter.removeListener
Parameters
- event: string | symbol
- listener: (...args: any[]) => void
  - - (...args: any[]): void
    - Parameters
      - Rest ...args: any[]
      Returns void
Returns this

resume

resume(): Promise<void>

- Defined in https://github.com/StoneT2000/Dimensions/blob/master/src/Agent/index.ts#L670
Resume an agent as long it is not terminated already

Returns Promise<void>

setMaxListeners

setMaxListeners(n: number): this

Inherited from Ladder.setMaxListeners

Overrides EventEmitter.setMaxListeners
Parameters
- n: number
Returns this

setupContainer

setupContainer(name: string, docker: Dockerode, engineOptions: EngineOptions): Promise<void>

- Defined in https://github.com/StoneT2000/Dimensions/blob/master/src/Agent/index.ts#L258
Parameters
- name: string
- docker: Dockerode
- engineOptions: EngineOptions
Returns Promise<void>

stop

stop(): Promise<void>

- Defined in https://github.com/StoneT2000/Dimensions/blob/master/src/Agent/index.ts#L654
Stop an agent provided it is not terminated. To terminate it, see _terminate;

Returns Promise<void>

timeout

timeout(): void

- Defined in https://github.com/StoneT2000/Dimensions/blob/master/src/Agent/index.ts#L687
timeout the agent

Returns void

write

write(message: string, callback: (error: Error) => void): boolean

- Defined in https://github.com/StoneT2000/Dimensions/blob/master/src/Agent/index.ts#L716
Write to stdin of the process associated with the agent

Parameters
- message: string
  
  the message
- callback: (error: Error) => void
  
  callback function
  
  returns true if written, false if highWaterMark reached
  - - (error: Error): void
    - Parameters
      - error: Error
      Returns void
Returns boolean

writeToErrorLog

writeToErrorLog(message: string): void

- Defined in https://github.com/StoneT2000/Dimensions/blob/master/src/Agent/index.ts#L737
Parameters
- message: string
Returns void

Static generateAgents

generateAgents(files: GenerationMetaData, options: DeepPartial<Options>, languageSpecificOptions?: LanguageSpecificOptions, agentSpecificOptions?: Array<DeepPartial<Options>>): Array<Agent>

- Defined in https://github.com/StoneT2000/Dimensions/blob/master/src/Agent/index.ts#L924
Generates a list of agents for use

Parameters
- files: GenerationMetaData
  
  List of files to use to make agents or a list of objects with a file key for the file path to the bot and a name key for the name of the agent
- options: DeepPartial<Options>
  
  Options to first override with for all agents
- Default value languageSpecificOptions: LanguageSpecificOptions = {}
  
  Options to second overrided with for agents depending on language
- Default value agentSpecificOptions: Array<DeepPartial<Options>> = []
  
  Options to lastly override with depending on agent's index
Returns Array<Agent>

Static listenerCount

listenerCount(emitter: EventEmitter, event: string | symbol): number

Inherited from Ladder.listenerCount
deprecated

since v4.0.0

Parameters
- emitter: EventEmitter
- event: string | symbol
Returns number

Object literals

streams

streams: object

Streams associated with the agent

err

err: null = null

in

in: null = null

out

out: null = null

Static OptionDefaults

OptionDefaults: object

Default Agent options

compileCommands

compileCommands: {}

Type declaration

detached

detached: false = false

id

id: null = null

image

image: string = "docker.io/stonezt2000/dimensions_langs"

logLimit

logLimit: number = 100000

loggingLevel

loggingLevel: INFO = Logger.LEVEL.INFO

maxCompileTime

maxCompileTime: number = 60000

maxInstallTime

maxInstallTime: number = 300000

name

name: null = null

runCommands

runCommands: {}

Type declaration

secureMode

secureMode: false = false

tournamentID

tournamentID: null = null

useCachedBotFile

useCachedBotFile: false = false

Hierarchy

Index

Enumerations

Interfaces

Type aliases

Constructors

Properties

Methods

Object literals

Type aliases

Static GenerationMetaData

Static GenerationMetaData_CreateMatch

Static GenerationMetaData_FilesOnly

Static GenerationMetaData_Tournament

Static ID

Static LanguageSpecificOptions

Type declaration

Constructors

constructor

Parameters

file: string

options: Partial<Options>

Default value languageSpecificOptions: LanguageSpecificOptions = {}

Returns Agent

Properties

_buffer

_clearTimer

_currentMovePromise

_currentMoveReject

_currentMoveResolve

_logsize

_trimmed

agentTimeStep

Private allowedToSendCommands

cmd

Private container

creationDate

currentMoveCommands

cwd

errorLogWriteStream

ext

file

id

Private log

logkey

memoryWatchInterval

messages

name

options

Private process

src

srcNoExt

status

tournamentID

version

Static defaultMaxListeners

Methods

_allowCommands

Returns void

_compile

Parameters

stderrWritestream: Writable

stdoutWritestream: Writable

engineOptions: EngineOptions

Returns Promise<void>

_disallowCommands

Returns void

_finishMove

Returns Promise<void>

_getProcess

Returns ChildProcess

_install

Parameters

stderrWritestream: Writable

stdoutWritestream: Writable

engineOptions: EngineOptions

Returns Promise<void>

_setTimeout

Parameters

fn: Function