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

Lease

A sidecar (<id>.lease) saying that something is alive and waiting.

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.

Waiter

The record’s note of who was last known to be waiting.

Enums

Answer

What the owner said.

ChoiceAction

What the daemon does to the task behind a question when a particular choice is answered.

QuestionStatus

Where a question is in its life.

Wait

How a wait over Question ended.

WaiterKind

Who is keeping watch over an open question.

Who

Who wrote one turn of a question’s conversation.

Constants

LEASE_TTL

How long a lease stays believable after its last beat.

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, Question::answer_timeout and now the waiter bookkeeping (Question::cwd, Question::waiter, Question::delivered_turns, Question::answer_delivered) - 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.

hand_over

Record that the agent has read everything so far, so the daemon waiter does not resume a session to tell it what was already printed.

notify

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

notify_text

notify for an event that is not a question: the same command, the same placeholders, with summary and run supplied directly.

parse_actions

Parse every --action value against the offered choices, refusing a label the question does not offer (it could never fire).

resume_wait

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

short_id

[short] for callers outside this module (a run id shortens the same way).

valid_asset_name

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