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:
| Expression | Resolves 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 else | used 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
readonlystrictMode: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?
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
JSON Schema describing the arguments the composite tool accepts.
spec
The composable pipeline specification to execute.
Returns
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
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
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
args
Record<string, unknown>
context
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:
spec.stepsmust be a non-empty array.- Every step must have a non-empty
toolstring.
Parameters
spec
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?
optionalerrors:string[]
valid
valid:
boolean
Example
const result = builder.validate(spec);
if (!result.valid) {
console.error('Invalid spec:', result.errors);
}