Module ask 

Questions: what an agent does when the next decision is the owner’s.

An agent that reaches a fork it has no authority to take - which storage backend, whether a breaking change is acceptable, which of two readings of the task is meant - has two options. It can guess, and produce an implementation the owner throws away; or it can stop and ask. This module is the second option, and it is the reason the graph can be left alone overnight without also being left to invent product decisions.

Stopping is cheap on purpose. The run parks as RunStatus::Waiting, which crate::daemon::settle refunds, so a question does not spend a task’s retry budget: an operator who asks twice would otherwise come back to a held task that never had a line of code judged.

Shape

Deliberately the same split as crate::queue. Question is data plus pure transitions - Question::answer is where a phone posting a choice the question never offered is rejected, and it touches no disk. Questions owns all I/O and is constructed with its root, so a test drives a real store in a temp directory without touching the operator’s real home.

One question is one JSON file under Questions’s root, written atomically. Files rather than a database because three processes read and write these records - the run that asked, magi web serving the phone, and magi answer at a terminal - and a rename is the only cross-process atomic write that needs no coordination between them. It is also why the wait below polls: the answer arrives in a file written by a process this one has no channel to.

Structs

Question

One decision magi will not take on the owner’s behalf.

Questions

A question store on disk.

Turn

One turn in a question’s back-and-forth, after the question itself was asked.

Enums

Answer

What the owner said.

QuestionStatus

Where a question is in its life.

Wait

How a wait over Question ended.

Who

Who wrote one turn of a question’s conversation.

Constants

PANEL_MAX_BYTES

Largest panel magi will store, html plus assets.

SCHEMA

On-disk format for a question. Bumped when a field’s meaning changes, or - as with Question::thread and now Question::answer_timeout - when a new field is added that a much older magi has no notion of at all.

WEB_URL_ENV

Environment variable naming the base URL of the web UI, for {url}.

Functions

ask_and_wait

File a question and wait for the owner, polling the store.

notify

Run the operator’s notification command, if one is configured.

resume_wait

Resume a wait already filed, without adding a turn or notifying again.

valid_asset_name

The one asset filename rule, applied on write and on read.