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
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
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:
- It is at the
'session'tier. - Its usage stats meet
EmergentConfig.promotionThreshold:totalUses >= threshold.usesconfidenceScore >= 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
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
Returns
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:
- AdaptPersonalityTool — bounded HEXACO trait mutation.
- ManageSkillsTool — runtime skill enable/disable/search.
- CreateWorkflowTool — multi-step tool composition.
- 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
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.
- Generate unique tool ID.
- Build or validate implementation (compose vs. sandbox).
- Execute all declared test cases and collect results.
- Submit candidate to the judge for creation review.
- If approved: refuse a tool whose test output JSON cannot write
(
test_output_unserializable), else create EmergentTool, register at session tier, index. - 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
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?
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
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
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
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
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.