Skip to content

Composing & extending ​

One assistant turn · an approved change1PERSON · ASSISTANT:USEStart a turnAppend the person’s message.The engine opens a turn on their thread.short engine calls record progress2HOST · ASSISTANT:RUNTake the lease and run the modelOne run may write at a time.Model calls happen outside transactions.a gated tool call pauses for approval3PERSON · EXACT APPROVALReview the proposed changeDigest binds input, operation and version.Deny or let it expire: no execution claim.only the approved call may be claimed4HOST · CHECK BEFORE EXECUTINGClaim once, execute, recordChanged input or a second claim is refused.The target still checks its own permissions.
The engine records and gates the turn. The host runs it. The execution claim cannot make an external effect atomic with the conversation record. Host integration is still to come.

The engine never calls a model. A host runs the loop and writes the result through the engine:

  1. A person says something: sendMessage appends their message and begins a turn.
  2. The host takes the lease with acquireRun, then calls the model and its tools.
  3. The host appends what happened with appendEvents: text, tool calls, sources.
  4. 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.
  5. 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.
  6. The host takes the lease again, calls claimExecution with 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.

ts
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.