ExecutionContext
ExecutionContext is the context object for one executor run. It includes the trace ID, executor metadata, execution metadata, and attributes.
import type { ExecutionContext } from "llm-exe";
type ExecutionContextShape<I, O> = {
traceId?: string;
executor: {
id: string;
type: string;
name: string;
created: number;
executions: number;
metadata?: Record<string, any>;
};
execution: {
start: number | null;
end: number | null;
input: I;
handlerInput?: any;
handlerOutput?: any;
output?: O;
errorMessage?: string;
error?: Error;
errorCategory?: string;
errorCode?: string;
errorContext?: unknown;
errorCause?: unknown;
};
attributes: Record<string, any>;
};Where ExecutionContext Is Available
ExecutionContext is exposed in three places:
- Parser callbacks —
createCustomParser(name, (text, context) => ...) - Hooks — the first argument to
onSuccess,onError, andonCompleteis execution metadata; pair it with the executor metadata as the second argument - Trace IDs —
execute(input, { traceId })orexecutor.withTraceId(id)setstraceIdon the context surfaced to parsers and hooks
createCoreExecutor(handler) wraps a plain function, and that function only receives the executor input — it does not currently receive an ExecutionContext argument.
Parser Callbacks
Custom parser callbacks receive ExecutionContext as the second argument.
const parser = createCustomParser("example", (text, context) => {
return {
text,
input: context?.execution.input,
executorName: context?.executor.name,
traceId: context?.traceId,
};
});Execution data is available on context.execution. Executor metadata is available on context.executor.
Trace IDs
Pass traceId in the options to execute() to tag one call:
const executor = createLlmExecutor({ llm, prompt, parser });
await executor.execute({ input: "hello" }, { traceId: "req-123" });withTraceId() sets a trace ID on the executor instance instead, and every call on that executor shares it. If one executor serves concurrent requests, they overwrite each other's ID, so use the per-call option there. When both are set, the per-call traceId wins and the instance value stays unchanged.
The trace ID is included in ExecutionContext, hook metadata, and deprecation warning details. It isn't attached to errors thrown by provider requests.
Error Metadata
When an execution throws an LlmExeError, structured error fields are copied into execution metadata:
executor.on("onError", (exec) => {
console.log(exec.errorCode);
console.log(exec.errorCategory);
console.log(exec.errorContext);
});Plain Error values still populate error and errorMessage.
