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.

Enums

Answer

What the owner said.

QuestionStatus

Where a question is in its life.

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.

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.

valid_asset_name

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