Skip to main content

Class: EmergentCapabilityEngine

Defined in: packages/agentos/src/cognition/emergent/EmergentCapabilityEngine.ts:576

Constructors​

Constructor​

new EmergentCapabilityEngine(deps): EmergentCapabilityEngine

Defined in: packages/agentos/src/cognition/emergent/EmergentCapabilityEngine.ts:613

Create a new EmergentCapabilityEngine.

Parameters​

deps​

EmergentCapabilityEngineDeps

All collaborator dependencies. See EmergentCapabilityEngineDeps.

Returns​

EmergentCapabilityEngine

Methods​

[FORGE_TRACE_DELIVER]()​

[FORGE_TRACE_DELIVER](trace): Promise<void>

Defined in: packages/agentos/src/cognition/emergent/EmergentCapabilityEngine.ts:777

Internal

Hands a forge's trace to the host's onForgeTrace and writes the forge's log line. Every layer that ends a forge (this engine, forge_tool, the wrapper, the orchestrator) delivers through this one method. Never throws.

Parameters​

trace​

ForgeTrace

The forge's trace.

Returns​

Promise<void>


checkPromotion()​

checkPromotion(toolId): Promise<PromotionResult | null>

Defined in: packages/agentos/src/cognition/emergent/EmergentCapabilityEngine.ts:1300

Check if a tool is eligible for promotion and auto-promote if the threshold is met.

A tool qualifies for promotion when:

  1. It is at the 'session' tier.
  2. Its usage stats meet EmergentConfig.promotionThreshold:
    • totalUses >= threshold.uses
    • confidenceScore >= threshold.confidence

When eligible, the engine submits the tool to the judge's promotion panel. If both reviewers approve, the tool is promoted to 'agent' tier.

Parameters​

toolId​

string

The ID of the tool to check.

Returns​

Promise<PromotionResult | null>

A PromotionResult if promotion was attempted, or null if the tool is not eligible or does not exist.


cleanupSession()​

cleanupSession(sessionId): EmergentTool[]

Defined in: packages/agentos/src/cognition/emergent/EmergentCapabilityEngine.ts:1442

Clean up all session tools for a given session.

Delegates to the registry's EmergentToolRegistry.cleanupSession() method and clears the local session index. A tool forged in the session and promoted out of it since (now at the agent tier) is not the session's any more: it stays held, registered and indexed under its agent.

Parameters​

sessionId​

string

The session identifier to clean up.

Returns​

EmergentTool[]

the tools the cleanup removed.


createExecutableTool()​

createExecutableTool(tool): EmergentExecutableTool

Defined in: packages/agentos/src/cognition/emergent/EmergentCapabilityEngine.ts:2647

Create an executable ITool wrapper for a forged emergent tool.

The wrapper refuses a call to a tool that is not active and, for an agent-tier tool, a call from any agent but its own, before anything runs or a use is recorded; it then performs runtime output validation, usage tracking, and promotion checks after each successful execution. A call whose tool was removed, or replaced under its id, while it ran returns its result, effects included, and records no use.

Parameters​

tool​

EmergentTool

Returns​

EmergentExecutableTool


createSelfImprovementTools()​

createSelfImprovementTools(deps): Promise<ITool<any, any>[]>

Defined in: packages/agentos/src/cognition/emergent/EmergentCapabilityEngine.ts:2536

Factory method that creates the four self-improvement tools when config.selfImprovement?.enabled is true.

Returns an array containing:

  1. AdaptPersonalityTool — bounded HEXACO trait mutation.
  2. ManageSkillsTool — runtime skill enable/disable/search.
  3. CreateWorkflowTool — multi-step tool composition.
  4. SelfEvaluateTool — self-scoring with parameter adjustment.

Returns an empty array when self-improvement is disabled or the config is absent. Uses dynamic imports to avoid hard compile-time coupling to tool modules that may not yet exist.

Parameters​

deps​

SelfImprovementToolDeps

Runtime hooks for personality, skills, tools, and memory.

Returns​

Promise<ITool<any, any>[]>

Array of 0 or 4 ITool instances.


demoteTool()​

demoteTool(toolId, reason): Promise<boolean>

Defined in: packages/agentos/src/cognition/emergent/EmergentCapabilityEngine.ts:1683

Demote a tool: its confidence is reset, it is taken out of the executor, and no later load brings it back. Only reactivateTool does.

Parameters​

toolId​

string

reason​

string

Returns​

Promise<boolean>

false when the tool is unknown.


forge()​

forge(request, context): Promise<ToolForgeResult>

Defined in: packages/agentos/src/cognition/emergent/EmergentCapabilityEngine.ts:714

Forge a new tool from a request.

Runs test cases, submits the candidate to the LLM judge, and registers the tool at the 'session' tier if approved. Returns a ForgeResult with the tool ID on success, or an error / rejection verdict on failure.

Pipeline: 0. Hold the tool's name to the forge's name rule (forgedToolNameProblem): a refused name fails the forge before anything runs.

  1. Generate unique tool ID.
  2. Build or validate implementation (compose vs. sandbox).
  3. Execute all declared test cases and collect results.
  4. Submit candidate to the judge for creation review.
  5. If approved: refuse a tool whose test output JSON cannot write (test_output_unserializable), else create EmergentTool, register at session tier, index.
  6. If rejected: return failure with the judge's reasoning.

Every result carries the forge's trace as its last key, trace: what was asked, what ran, what the judge said and where the forge ended. The same trace goes to onForgeTrace, once, before the forge returns. A forge that throws records its trace on the call's record, hands it to onForgeTrace and rethrows the same value.

Parameters​

request​

ForgeToolRequest

The forge request describing the desired tool.

context​

The agent and session ids. caller is the forging call's own context: a composition's test steps run as that caller, so they meet the checks the caller's direct calls meet. forgeId and author are for a direct caller's trace.

agentId​

string

author?​

{ model?: string; provider?: string; }

Optional: who wrote the request, for the trace's provenance.

author.model?​

string

author.provider?​

string

caller?​

ToolExecutionContext

forgeId?​

string

Optional: this forge's trace id. Minted (a random UUID with the prefix forge_) when absent.

sessionId​

string

Returns​

Promise<ToolForgeResult>

A ForgeResult indicating success or failure, with its trace.


getAgentTools()​

getAgentTools(agentId): EmergentTool[]

Defined in: packages/agentos/src/cognition/emergent/EmergentCapabilityEngine.ts:1422

Get all agent-tier tools for a given agent ID.

Parameters​

agentId​

string

The agent identifier.

Returns​

EmergentTool[]

An array of EmergentTool objects created by the agent.


getSessionTools()​

getSessionTools(sessionId): EmergentTool[]

Defined in: packages/agentos/src/cognition/emergent/EmergentCapabilityEngine.ts:1396

Get all session-scoped tools for a given session ID.

Parameters​

sessionId​

string

The session identifier.

Returns​

EmergentTool[]

An array of EmergentTool objects belonging to the session.


loadPersistedTools()​

loadPersistedTools(options): Promise<LoadPersistedToolsResult>

Defined in: packages/agentos/src/cognition/emergent/EmergentCapabilityEngine.ts:1557

Load the stored tools of the given tiers into the running process.

Call it at start, after the host's own tools are registered. For each row it reads the source (raw code, code with its list, a redacted record, or a composition), keeps a demoted row off, suspends a row that cannot be rebuilt, and registers the rest. A row is never rewritten by being loaded, and a stored request is never replaced by a derived one. One line is logged per tool that did not load. A row whose load throws is reported in failed and does not stop the others.

shared rows load for every caller. agent rows are those of options.agentId and session rows those of options.sessionId, and naming either tier without its selector throws (selector_required), so a shared store never puts one agent's private tools in another's executor. A loaded or forged agent tool also refuses a call from any other agent (see createExecutableTool). The agent identity is the persona id: forge_tool records the forging caller's personaId as created_by_agent, and agentId here is that id. Rows written by releases before this one hold the forging GMI instance's id instead.

Parameters​

options​

LoadPersistedToolsOptions

Returns​

Promise<LoadPersistedToolsResult>


onHostToolRegistered()​

onHostToolRegistered(toolName): Promise<void>

Defined in: packages/agentos/src/cognition/emergent/EmergentCapabilityEngine.ts:1720

Called by the host when any tool is registered. A composition the library suspended because a step was missing, refused, replaced or circular is checked again when a tool one of its steps names arrives, and registered when it fits. A host's own suspension is left to the host.

Parameters​

toolName​

string

Returns​

Promise<void>


reactivateTool()​

reactivateTool(toolId): Promise<LoadedToolOutcome | undefined>

Defined in: packages/agentos/src/cognition/emergent/EmergentCapabilityEngine.ts:1710

Re-check one suspended or demoted tool against the configuration in force and, when it fits, register it again. This is how a host clears a suspension or a demotion it set; the library never does so on its own.

Parameters​

toolId​

string

Returns​

Promise<LoadedToolOutcome | undefined>

the outcome, or undefined when the tool is unknown.


removeTool()​

removeTool(toolId): Promise<EmergentTool | undefined>

Defined in: packages/agentos/src/cognition/emergent/EmergentCapabilityEngine.ts:1518

Remove a previously synced tool from the live runtime and registry.

Parameters​

toolId​

string

Returns​

Promise<EmergentTool | undefined>


suspendTool()​

suspendTool(toolId, reason): Promise<boolean>

Defined in: packages/agentos/src/cognition/emergent/EmergentCapabilityEngine.ts:1655

Suspend a tool and take it out of the executor. The state write is awaited, so the suspension survives a restart, and no later use, rewrite or load turns the tool back on. The suspension is recorded as the host's, so it stays, whatever its reason says, until reactivateTool is called.

Parameters​

toolId​

string

reason​

string

Returns​

Promise<boolean>

false when the tool is unknown.


syncPersistedTool()​

syncPersistedTool(tool): Promise<LoadedToolOutcome>

Defined in: packages/agentos/src/cognition/emergent/EmergentCapabilityEngine.ts:1475

Hydrate one stored tool and make it executable.

Parameters​

tool​

EmergentTool

Returns​

Promise<LoadedToolOutcome>

what happened, so a host can tell a registered tool from a refused one.

Deprecated​

Use loadPersistedTools, which reads the rows itself. This applies the same checks to the one tool: a suspended or demoted tool is not registered, and a tool whose source cannot be rebuilt is suspended. When the tool has a stored row, that row is what is read, not the object passed in (a host-built object can carry a list the host made up), and a load never rewrites it. A tool with no row gets its row written first, as before, so its uses are recorded and the next load finds it.