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 | McpServer)[];
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 | McpServer)[]default []App tools this extension adds, named <name>__<tool>. In Python they see no deps. 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). In Python they see no deps. 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.