Waiting

A mandate often has to wait: for a reply, for a scheduled time, or for a person to decide.

A mandate spends most of its time waiting. A supplier replies the next day, an approval takes a few hours, a delivery confirms at the end of the week. While a mandate waits, Shadway saves it and stops running it. It uses no model calls and costs nothing until something wakes it up: a reply, a set time, or a person's decision.

The four kinds of wait

The status tells you what the mandate is waiting for. waiting_external means it is waiting for a reply, a timer, or free capacity to run. needs_approval means it is waiting for a person to approve an action or answer a question.

The agent can only wait for real replies

The agent can only wait for a reply to something it actually did. If it sent an email, it can wait for the reply. If it placed a call, it can wait for the call to finish. Only the matching reply wakes the mandate. An unrelated webhook, or an approval about something else, never wakes a mandate that is waiting on a supplier.

Shadway checks this when the wait starts. Say the agent tries to wait for a reply to an email, but the email was blocked and never went out. There is nothing that could reply, so Shadway refuses the wait and the agent has to plan again. A mandate can never sit waiting for a reply that can't come.

What happens on a timeout

Every wait has a time limit. What happens when it runs out depends on what the mandate was waiting for:

• Waiting for a reply or a timer: the agent wakes up without the reply and decides what to do next. It can follow up, try someone else, or report what it knows. The default limit for a reply is 24 hours.
• Waiting for a person: if an approval or a question times out, the mandate stops with the status paused and keeps everything it has learned. Resume it whenever someone is ready. If a decision arrives after the approval has expired, Shadway refuses it and does not run the action.

See what a mandate is waiting for

currentState.waitingOn describes the current wait in plain words. Show it in your app so people know why the work is waiting.

const current = await shadway.mandate(mandateId).get();

if (current.status === "waiting_external" || current.status === "needs_approval") {
  console.log(current.currentState.waitingOn ?? "Waiting");
}

current, err := client.Mandate(mandateID).Get(ctx)
if err != nil {
	log.Fatal(err)
}

switch current.Status {
case shadway.MandateStatusWaitingExternal, shadway.MandateStatusNeedsApproval:
	if current.CurrentState.WaitingOn != nil {
		fmt.Println(*current.CurrentState.WaitingOn)
	}
}

A mandate with the status paused needs a command to start again. See pause, resume, and cancel. A waiting mandate needs nothing from you: it starts again on its own when the reply, timer, or decision arrives.

What waiting costs

A waiting mandate uses no model calls. A mandate that waits three weeks and works for six minutes costs you six minutes. You can see this in the record: there are no model calls between the action and the reply.

Continue building