Skip to main content

Class: ComposableToolBuilder

Defined in: packages/agentos/src/cognition/emergent/ComposableToolBuilder.ts:102

Builds composite ITool instances by chaining existing tool invocations.

Each invocation is described by a ComposableStep that maps values from a shared pipeline context into the step tool's arguments via a lightweight reference expression syntax:

ExpressionResolves to
"$input.foo"args.foo from the composite tool's own input
"$input"the whole input object
"$prev.bar"bar from the previous step's output
"$prev"the previous step's full output
"$steps[0].output.data"output.data from the first step's output
"$steps[0]"the first step's full output
anything elseused as a literal value without transformation

Reference expressions nested inside plain objects are resolved recursively, so { query: "$input.topic", limit: 10 } becomes { query: "actual-topic", limit: 10 }.

Every step runs through a StepGate, which is where the host's checks live, and is checked first against the chainability rule: a tool that declares no side effects is chained freely, a tool with side effects only when the host lists it, and a tool that declares nothing by no one.

Example​

const builder = new ComposableToolBuilder(
createStepGate({ resolve: (name) => registry.get(name) }),
);
builder.bind({ sideEffectingTools: ['send_email'] });

const spec: ComposableToolSpec = {
mode: 'compose',
steps: [
{ name: 'search', tool: 'web_search', inputMapping: { query: '$input.topic' } },
{ name: 'summarise', tool: 'summarise_text', inputMapping: { text: '$prev.snippet' } },
],
};

const tool = builder.build('research', 'Search then summarise a topic', schema, spec);
const result = await tool.execute({ topic: 'quantum computing' }, ctx);

Constructors​

Constructor​

new ComposableToolBuilder(gateOrExecute, options?): ComposableToolBuilder

Defined in: packages/agentos/src/cognition/emergent/ComposableToolBuilder.ts:122

Parameters​

gateOrExecute​

A StepGate. A bare (toolName, args, context) callback is still accepted so existing construction keeps working, but nothing can be composed through one: it cannot say what a step tool is, so no step can be checked. Bind a gate with bind.

StepGate | (toolName, args, context) => Promise<ToolExecutionResult<any>>

options?​

Optional builder configuration.

strictMode?​

boolean

When true, unresolved reference expressions throw an error instead of falling through as literal strings.

Returns​

ComposableToolBuilder

Properties​

strictMode​

readonly strictMode: boolean

Defined in: packages/agentos/src/cognition/emergent/ComposableToolBuilder.ts:108

When true, unresolved $-prefixed reference expressions throw instead of silently passing through as literal strings. Useful for development and testing to catch typos in inputMapping expressions early.

Methods​

bind()​

bind(options): void

Defined in: packages/agentos/src/cognition/emergent/ComposableToolBuilder.ts:137

Bind the gate and the host's list of side-effecting tools that may be chained. The engine calls this from its configuration; a host that uses the builder on its own may call it too.

Parameters​

options​
gate?​

StepGate

sideEffectingTools?​

readonly string[]

Returns​

void


build()​

build(name, description, inputSchema, spec): ITool

Defined in: packages/agentos/src/cognition/emergent/ComposableToolBuilder.ts:206

Build an ITool-compatible object from a ComposableToolSpec.

The returned tool can be registered directly with any tool orchestrator that accepts ITool. Its execute method runs the step pipeline sequentially, threading outputs through the reference resolution system.

Parameters​

name​

string

Machine-readable tool name exposed to the LLM (e.g. "research_topic").

description​

string

Natural language description of what the composite tool does.

inputSchema​

JSONSchemaObject

JSON Schema describing the arguments the composite tool accepts.

spec​

ComposableToolSpec

The composable pipeline specification to execute.

Returns​

ITool

A fully-formed ITool instance whose execute method runs the pipeline.

Example​

const tool = builder.build(
'fetch_and_summarise',
'Fetch a URL then return a one-paragraph summary.',
{ type: 'object', properties: { url: { type: 'string' } }, required: ['url'] },
spec,
);

check()​

check(stepTool): Chainability

Defined in: packages/agentos/src/cognition/emergent/ComposableToolBuilder.ts:157

Whether a step naming this tool may be chained right now.

Parameters​

stepTool​

string

Returns​

Chainability


hasGate()​

hasGate(): boolean

Defined in: packages/agentos/src/cognition/emergent/ComposableToolBuilder.ts:147

Whether steps can be resolved and checked at all.

Returns​

boolean


hasSideEffectingStep()​

hasSideEffectingStep(spec): boolean

Defined in: packages/agentos/src/cognition/emergent/ComposableToolBuilder.ts:168

Whether any step of the spec names a tool that has side effects right now, or a tool that is itself a composition (whose own steps may).

Parameters​

spec​

ComposableToolSpec

Returns​

boolean


resolve()​

resolve(stepTool): ITool<any, any> | undefined

Defined in: packages/agentos/src/cognition/emergent/ComposableToolBuilder.ts:152

The tool a step names, as the gate resolves it now; undefined without a gate.

Parameters​

stepTool​

string

Returns​

ITool<any, any> | undefined


runPipeline()​

runPipeline(spec, args, context, options?): Promise<ToolExecutionResult<any>>

Defined in: packages/agentos/src/cognition/emergent/ComposableToolBuilder.ts:244

Run a pipeline. Every step is re-checked against the chainability rule before it runs, because a tool is replaced by name, and the instance that was checked is the one the gate runs. With options.dry (forge-time tests), a step whose tool has side effects, or is itself a composition, is not executed: its output is taken from stepOutputs, and the step is listed as an effect that would have run. options.signal, when given, reaches every step's run.

Compositions nest no deeper than MAX_COMPOSITION_DEPTH: the depth travels in context.sessionData.emergentDepth, and a run at the limit is refused with nesting_too_deep, a code no composition is suspended for (a chain that long is not a cycle; the engine refuses a composition that reaches itself at its own call).

A refusal or a failure ends the run; details then names the step, the steps that completed before it, and the effects so far.

Parameters​

spec​

ComposableToolSpec

args​

Record<string, unknown>

context​

ToolExecutionContext

options?​
dry?​

{ stepOutputs: Record<string, unknown>; }

dry.stepOutputs​

Record<string, unknown>

signal?​

AbortSignal

Returns​

Promise<ToolExecutionResult<any>>


validate()​

validate(spec): object

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

Validate a ComposableToolSpec before building.

Performs structural checks only — it does not verify that the referenced tool names are actually registered in any registry. Use this method to give early, actionable feedback before attempting to build a tool.

Checks performed:

  1. spec.steps must be a non-empty array.
  2. Every step must have a non-empty tool string.

Parameters​

spec​

ComposableToolSpec

The spec to validate.

Returns​

object

{ valid: true } when the spec passes all checks, or { valid: false, errors: string[] } with one message per failing check.

errors?​

optional errors: string[]

valid​

valid: boolean

Example​

const result = builder.validate(spec);
if (!result.valid) {
console.error('Invalid spec:', result.errors);
}