Composing & extending
The engine never calls a model. A host runs the loop and writes the result through the engine:
- A person says something:
sendMessageappends their message and begins a turn. - The host takes the lease with
acquireRun, then calls the model and its tools. - The host appends what happened with
appendEvents: text, tool calls, sources. - A tool that changes something is proposed with an
approval-request. Its digest binds the person who may approve, the thread, the call, the operation, the input, the deployed version, an expiry and a one-time value. The turn rests there. - The person approves or denies with
resolveApproval, passing the digest they were shown. An approval after the expiry, or under a newer deploy, is refused; a denial always works. - The host takes the lease again, calls
claimExecutionwith the operation and input it is about to run, and runs the operation only if that returns.
Registering the engine
The package is public on npm; add it to the vertical like any other engine dependency.
import { assistantModule } from '@substrat-run/engine-assistant';
host.registerModule(assistantModule);Call the in-scope functions inside the host's transactions, with the caller permissions checked at the boundary. The stream vocabulary and approvalDigest come from @substrat-run/contracts/assistant-stream.
Resuming after an answer
An approval or denial resumes the turn. After either answer, the host must take the lease and write turn-finish or turn-error; until then, new owner messages fail with turn_in_progress. A later run can take over a stale lease and close an abandoned turn. Without a run, the owner's way out is to close the thread.
The execution claim cannot be atomic with a tool's external effect. Handle recovery if the host stops after claiming, and let the target operation check its own permissions. An approval grants no target authority.