Module talk 

The standing conversation: a place to think out loud with an agent between tasks, reachable from a phone.

This is a conversation that stays open. Ask a question, have the agent read a file or run a command to check something, talk through an idea, and when it is time to act, tell it to file the work rather than do it here. The conversation does not end; it is what the operator opens the next time something comes up.

Talking is not implementing

Every turn here runs with allow_write: false by default, for a reason that is not security, but attribution. An agent that edits a checkout mid-conversation leaves a diff that belongs to no run and passed no review, and on a repository entered into magi’s blind competition that makes every candidate’s diff unjudgeable. That is why the default holds regardless of what a repository’s own magi.toml says about anything else. When the operator wants a change made, the agent is told to run magi task add --solo (briefing) rather than reach for an editor: the change goes through magi’s own queue, on the repository’s own terms, and the operator can watch it happen instead of trusting that it did.

[talk] allow_write (crate::config::Talk::allow_write) lets a specific repository opt out of that default - a dotfiles or personal config checkout that is never entered into a competition and never reviewed has nothing for the restriction to protect, and filing a task for a one-line edit there is pure overhead. Turning it on does not turn this conversation into an implementer: briefing still sends everything bigger than a small, operator-named edit to the queue, and still tells the agent to say what it changed.

--solo rather than a plain magi task add is the point of pairing this module with crate::queue::Task::solo. A task that came out of a conversation the operator just had is a decision already made, not a design question worth three independent takes - so it runs through one implementer and straight into review, the way crate::graph::Runner already degrades a single-candidate run.

Shape

The same split crate::queue uses: Talk is data plus pure helpers, Talks owns the I/O and is constructed with its root, so every test here drives a real store in a temp directory rather than the operator’s own home.

Structs

Attachment

One image the operator attached to a turn.

Talk

One standing conversation.

Talks

A conversation store on disk.

Turn

One message in the conversation.

Enums

TalkStatus

Where a conversation is in its life: this conversation can file any number of tasks without ending, so it only ever moves once, from open to closed.

Who

Who said something.

Constants

SCHEMA

On-disk format for a conversation. Bumped when a field’s meaning changes.

Functions

begin

Open a conversation. Takes no agent turn: there is no idea to answer yet, and a conversation the operator has not said anything into yet is a normal, valid thing to have sitting on the phone.

briefing

The briefing the agent opens with, sent once as part of its first turn.

clear_pending

Discard the durable draft without adding a transcript turn.

clear_pending_if_matches

Clear a draft only when the caller still sees its complete snapshot.

close

Close a conversation. Idempotent: closing an already-closed conversation is not an error, since the operator’s intent - “I am done with this” - is already satisfied.

drain

Promote the current durable draft to one operator turn.

edit_pending_text

Replace just the text of the durable draft, but only if the caller’s snapshot still identifies the entire draft. This refuses to overwrite a message another client queued or a draft the drain already promoted.

queue

Add an unrecorded message to the durable draft while another turn runs.

record

Append the operator’s turn and flush it, without invoking anything.

reopen

Reopen a closed conversation. Idempotent for the same reason close is: reopening an already-open conversation is not an error, since the operator’s intent - “I want to keep talking about this” - is already satisfied.

respond

The agent’s half of a turn: invoke, append, flush. Pairs with record.

say

One operator turn and one agent turn, appended - the synchronous form, used by tests and by anything that is fine waiting out the turn itself.

tasks_of

Queue tasks this conversation has filed, oldest first.

valid_attachment_id

Is id a shape put_attachment could have produced? 32 lowercase hex digits and nothing else, checked before an id that came from the client is ever allowed to build a path - so .. and a path separator are never even possible.