Session settings and states
The agent settings that drive pause and resume, the states of an environment, and the directive that stops a run.
Agent settings
These are settings of the agent in Blaise, not of the runner. The idle policy and the paused lifetime are edited in the agent's settings in the dashboard. The inactivity limit and the timeout keep their defaults for now.
| Setting | Values | Default | Description |
|---|---|---|---|
| Idle policy | pause, end | pause | What happens to a session with no activity for the inactivity limit. pause keeps the environment; end completes the session and tears it down. |
| Paused lifetime | up to the maximum | 1 day | How long a paused session waits for a message before it is torn down. The dashboard offers 1 hour to 7 days. |
| Inactivity limit | milliseconds | 5 min | How long a session may go without a message or prompt before it is idle. Never counts while a turn runs. |
| Timeout | milliseconds | 30 min | The longest a single run may take. The run is told to stop with the reason timeout. |
The maximum paused lifetime is set by the operator of the server with
SESSION_MAX_PAUSED_LIFETIME_MS (default 7 days). An agent that asks for more gets the maximum.
blaise-agent listen reads the idle policy when it starts. With the pause policy it refuses to
start if a plug of the configuration cannot resume (see
Resolving plugs).
Environment states
| State | Meaning |
|---|---|
active | A run is in progress or about to start. |
paused | No run. The environment is kept until the next message or until it expires. |
tearing_down | The session is over. The plugs are being torn down, or a retry is due. |
ended | Torn down. The persisted plug state is deleted. |
orphaned | Teardown kept failing and Blaise gave up. Needs a person: see handle an orphaned environment. |
Run kinds
| Kind | ctx.run.kind | Handlers | Agent |
|---|---|---|---|
start | start | onSession, then onTeardown if the session is over | yes |
resume | resume | onSession, then onTeardown if the session is over | yes |
teardown | teardown | onTeardown | no |
ctx.run.number counts the runs of the session from 1.
Stop reasons
Blaise sends a stop directive on the stream it already uses for prompts and cancellations. It
carries a reason and mayResume.
| Reason | When | mayResume |
|---|---|---|
idle | No activity for the inactivity limit, with the pause policy | true, unless a plug cannot resume |
completed | No activity with the end policy | false |
closed | Someone ended the session | false |
cancelled | Reserved: the runner understands it, but Blaise does not send it yet | false |
timeout | The run exceeded the agent's timeout | false |
Blaise records a stop before it sends it, and sends it once the record is committed. Ending a session returns an error, and changes nothing, when no runner receives the stop.
A stop is delivered only to a runner that is connected. A run that ignores a timeout stop, or that
no runner is connected to, is failed by Blaise after a minute; one that ignores another stop is
caught by the usual timeouts. The reasons failed (the run broke) and expired (the session was
paused for too long) are never sent: the first is reported by the run, and the second only reaches a
teardown run.
PauseInfo.mayResume and TeardownInfo.reason in the plug API carry the same values to plugs.
blaise:shell exposes them to scripts as $BLAISE_MAY_RESUME and $BLAISE_END_REASON.
What a run reports
| Report | When |
|---|---|
| Whether the chain can resume | Once the plugs are loaded. Blaise never pauses a chain that cannot resume. |
| The pause | When the run ends, before the teardown that may follow, with the ACP session. |
| The teardown | When the plugs are torn down, with whether it succeeded. |
| Orphaned state | When a stored record belongs to no plug of the configuration. |
A run that breaks before it can report its pause reports a failure, so Blaise does not wait for it. If the pause that ends a session cannot be reported, the run still tears its plugs down before it fails.