extension
The one extension primitive: tools, trusted instructions and hooks.
Trusted host code, not a security boundary.
Import from @threads/core (TypeScript) or threads (Python).
function extension(options: {
name: Name;
tools?: readonly Tool[];
instructions?: string;
hooks?: Hooks<Deps>;
on?: Record<string, (event: Event) => Promise<void>>;
setup?: () => Promise<void>;
hookTimeoutMs?: PosInt;
}): Extension<Deps>Parameters
nameNamerequiredUnique; tools are namespaced <ext>__<tool>.
toolsreadonly Tool[]default []App tools this extension adds, named <name>__<tool>; they get the run's deps, like the agent's own tools. Default [] adds none.
instructionsstringStatic; goes into the system prompt after the base instructions.
hooksHooks<Deps>default {}Lifecycle hooks that can block or change what a run does (see Hooks); each gets the run's deps in its ctx. Default {} adds none. See Hooks.
onRecord<string, (event: Event) => Promise<void>>default {}Observers keyed by event type, or "*". Committed events, delivered after append; can't block or change execution.
on(event)EventrequiredOne committed event of the type the key names (any type for "*"), delivered after it was appended to the log.
setup() => Promise<void>Runs once at check() or first run. Throwing is a ConfigError. Omitted: nothing runs at setup.
hookTimeoutMs / hook_timeout_msPosIntdefault 5000The time limit, in milliseconds, for each hook call. A hook that runs longer counts as a failed call, the same as one that throws. A positive whole number; default 5000.