Skip to main content

Class: ForgeToolMetaTool

Defined in: packages/agentos/src/cognition/emergent/ForgeToolMetaTool.ts:187

Meta-tool enabling agents to create new tools at runtime.

Only registered when the agent is configured with emergent: true. Adds ~120 tokens to the tool list. Agents provide: name, description, schemas, implementation (compose existing tools or write sandboxed code), and test cases.

Example​

const metaTool = new ForgeToolMetaTool(engine);
// Register with ToolOrchestrator:
orchestrator.registerTool(metaTool);

// Agent calls via tool-call interface:
const result = await metaTool.execute({
name: 'add_numbers',
description: 'Add two numbers together.',
inputSchema: { type: 'object', properties: { a: { type: 'number' }, b: { type: 'number' } } },
outputSchema: { type: 'object', properties: { sum: { type: 'number' } } },
implementation: {
mode: 'sandbox',
code: 'function execute(input) { return { sum: input.a + input.b }; }',
allowlist: [],
},
testCases: [{ input: { a: 2, b: 3 }, expectedOutput: { sum: 5 } }],
}, context);

Implements​

Constructors​

Constructor​

new ForgeToolMetaTool(engine): ForgeToolMetaTool

Defined in: packages/agentos/src/cognition/emergent/ForgeToolMetaTool.ts:345

Create a new ForgeToolMetaTool.

Parameters​

engine​

EmergentCapabilityEngine

The EmergentCapabilityEngine that will handle the actual forge pipeline (build → test → judge → register).

Returns​

ForgeToolMetaTool

Properties​

category​

readonly category: "emergent" = 'emergent'

Defined in: packages/agentos/src/cognition/emergent/ForgeToolMetaTool.ts:204

Optional

Optional. A category or group to which this tool belongs (e.g., "data_analysis", "communication", "file_system", "image_generation"). This is useful for organizing tools, for filtering in UIs or registries, and potentially for aiding an LLM in selecting from a large set of tools.

Implementation of​

ITool.category


description​

readonly description: string

Defined in: packages/agentos/src/cognition/emergent/ForgeToolMetaTool.ts:198

A detailed, natural language description of what the tool does, its primary purpose, typical use cases, and any important considerations or limitations for its use. This description is critical for an LLM to understand the tool's capabilities and make informed decisions about when and how to invoke it. It should be comprehensive enough for the LLM to grasp the tool's semantics.

Implementation of​

ITool.description


displayName​

readonly displayName: "Forge Tool" = 'Forge Tool'

Defined in: packages/agentos/src/cognition/emergent/ForgeToolMetaTool.ts:195

A concise, human-readable title or display name for the tool. Used in user interfaces, logs, or when presenting tool options to developers or users.

Example​

"Web Search Engine", "Advanced Python Code Interpreter"

Implementation of​

ITool.displayName


hasSideEffects​

readonly hasSideEffects: true = true

Defined in: packages/agentos/src/cognition/emergent/ForgeToolMetaTool.ts:207

Optional

Optional. Indicates if the tool might have side effects on external systems (e.g., writing to a database, sending an email, making a purchase, modifying a file). Defaults to false if not specified. LLMs or orchestrators might handle tools with side effects with greater caution, potentially requiring explicit user confirmation.

Implementation of​

ITool.hasSideEffects


id​

readonly id: "com.framers.emergent.forge-tool" = 'com.framers.emergent.forge-tool'

Defined in: packages/agentos/src/cognition/emergent/ForgeToolMetaTool.ts:189

A globally unique identifier for this specific tool (e.g., "web-search-engine-v1.2", "stock-price-fetcher"). This ID is used for internal registration, management, and precise identification. It's recommended to use a namespaced, versioned format (e.g., vendor-toolname-version).

Implementation of​

ITool.id


inputSchema​

readonly inputSchema: JSONSchemaObject

Defined in: packages/agentos/src/cognition/emergent/ForgeToolMetaTool.ts:210

The JSON schema defining the structure, types, and constraints of the input arguments object that this tool expects. This schema is used by:

  1. LLMs: To construct valid argument objects when requesting a tool call.
  2. ToolExecutor: For validating the arguments before invoking the tool's execute method. ToolExecutor reads it as JSON Schema draft-07, coercing an argument to the type the schema names where it can and filling in a default the schema gives. A call to a tool whose input schema does not compile fails, and the tool does not run.

See​

https://json-schema.org/

Implementation of​

ITool.inputSchema


name​

readonly name: "forge_tool" = 'forge_tool'

Defined in: packages/agentos/src/cognition/emergent/ForgeToolMetaTool.ts:192

The functional name of the tool, as it should be presented to and used by an LLM in a tool call request (e.g., "searchWeb", "executePythonCode", "getWeatherForecast"). This name must be unique among the set of tools made available to a given GMI/LLM at any time. It should be concise, descriptive, and typically in camelCase or snake_case.

Implementation of​

ITool.name

Methods​

[FORGE_TRACE_DELIVER]()​

[FORGE_TRACE_DELIVER](trace): Promise<void>

Defined in: packages/agentos/src/cognition/emergent/ForgeToolMetaTool.ts:467

Internal

Hands a forge's trace to the engine's onForgeTrace and writes the forge's log line, through the engine's own delivery. Never throws.

Parameters​

trace​

ForgeTrace

The forge's trace.

Returns​

Promise<void>


execute()​

execute(args, context): Promise<ToolExecutionResult<ToolForgeResult>>

Defined in: packages/agentos/src/cognition/emergent/ForgeToolMetaTool.ts:382

Execute the forge pipeline via the engine.

Extracts the agent ID and session/correlation ID from the execution context and delegates to EmergentCapabilityEngine.forge.

Every call ends with one trace of the forge. The engine records the forges it runs; forge_tool records the ones it refuses before the engine runs (a self-change refusal, a refused name, a missing description) and the ones its own code throws on, and hands each to the engine's onForgeTrace. The result the model reads is the same either way.

Parameters​

args​

ForgeToolInput

The forge tool input arguments (name, description, schemas, implementation, test cases, and the optional justification).

context​

ToolExecutionContext

The tool execution context providing agent and session IDs.

Returns​

Promise<ToolExecutionResult<ToolForgeResult>>

A ToolExecutionResult wrapping the ForgeResult without its trace, which the model never reads.

Implementation of​

ITool.execute


refusalBeforeApproval()​

refusalBeforeApproval(_args, context): ToolExecutionResult<ToolForgeResult> | undefined

Defined in: packages/agentos/src/cognition/emergent/ForgeToolMetaTool.ts:359

The learning layer's refusal of a forge, before the approval gate: forging is a self-change on every call.

Parameters​

_args​

Record<string, any>

The forge arguments; the refusal does not depend on them.

context​

ToolExecutionContext

The call's context.

Returns​

ToolExecutionResult<ToolForgeResult> | undefined

Implementation of​

ITool.refusalBeforeApproval