remote

type Agent struct {
	// contains filtered or unexported fields
}

type ArchiveArgs struct {
	Dir      string `json:"dir"`
	Archived bool   `json:"archived"`
}

type AttachOptions struct {
	Open func(Hello) (*Session, error)

	// Host answers the version exchange (whois.go): which build is holding this
	// socket, whether it has work in flight, and whether it will retire.
	//
	// NIL IS "NOTHING IS HOLDING A CONVERSATION HERE" and it is the honest
	// answer for a pipe engine, which is why [Serve] leaves it unset. A pipe's
	// conversation cannot outlive its connection, so it can never be the stale
	// middle half this exchange exists to find.
	Host func(WhoIs) HostSelf
}

type AutonomyArgs struct {
	Kind   session.AskKind `json:"kind"`
	Policy session.Policy  `json:"policy"`
}

type Client struct {
	// contains filtered or unexported fields
}

type ConnectArgs struct {
	ID      string `json:"id"`
	Approve bool   `json:"approve,omitempty"`
	Key     string `json:"key,omitempty"`
}

type ConnectedArgs struct {
	Service string `json:"service"`
	Account string `json:"account"`
}

type ConsentArgs struct {
	ID    uint64               `json:"id"`
	Allow bool                 `json:"allow"`
	Scope session.ConsentScope `json:"scope,omitempty"`
}

type DepositedFile struct {
	Path string `json:"path"`
}

type Dialer func() (io.ReadWriteCloser, error)

type DirEntry struct {
	Name    string `json:"name"`
	Dir     bool   `json:"dir,omitempty"`
	Size    int64  `json:"size,omitempty"`
	ModTime int64  `json:"mtime,omitempty"`
	MIME    string `json:"mime,omitempty"`
}

type DirListing struct {
	Path      string     `json:"path"`
	Entries   []DirEntry `json:"entries"`
	Truncated bool       `json:"truncated,omitempty"`
}

type Driver struct {
	// Yours says the surface reading this frame is the one that drives. It is
	// the ordinary case and the only one that draws nothing.
	Yours bool `json:"yours,omitempty"`
	// Machine is the driver's machine name as [Hello.Surface] gave it, empty
	// when that surface sent none. It is sanitized ([machineLabel]) because it
	// is drawn.
	Machine string `json:"machine,omitempty"`
	// Here says the driver is another window on THIS surface's own machine,
	// which is the case a person reads as a window they forgot rather than as a
	// machine they walked away from.
	Here bool `json:"here,omitempty"`
}

type Engine struct {
	// Agent is the conversation the surface starts on. Required.
	Agent WrappedAgent
	// RefreshModelSources updates the engine's own agents from its own profile
	// immediately before a model-set call. It is nil for engines with no
	// profile behind them and changes no wire shape: the existing SetModel call
	// is the notification that a local surface has already written the row.
	RefreshModelSources func()
	// RefreshApprovals updates this conversation's running gate from the engine's
	// own profile immediately before a rule-scoped consent answer is applied.
	// It is nil for engines with no profile behind them and changes no wire
	// shape: the existing consent answer is the notification that a local
	// surface has already written the rule.
	RefreshApprovals func()
	// Closed is called once for each conversation this engine shut down, with
	// the agent that was closed, so the door that built it can forget it.
	//
	// IT IS THE PAIR OF WHATEVER REGISTERED THE AGENT, and it exists because
	// [Engine.RefreshModelSources] reaches the conversations its door is
	// holding: a door that registers and never forgets grows that list for as
	// long as the process lives, and an engine process outlives every
	// conversation in it. Nil for a door that retains nothing. It changes no
	// wire shape — a conversation ending is already the end of its stream.
	Closed func(agent WrappedAgent)
	// ProfileDir is the profile directory this engine process resolved. It is
	// carried in Welcome so a linked-local surface writes every local row back
	// to the profile the running conversation actually reads. A remote surface
	// does not use the path for local writes.
	ProfileDir string
	// Workspace is the directory the engine resolved and works in — the answer
	// to the path the hello asked for, which the welcome carries back.
	Workspace string
	// SessionFile is the transcript being written, and Resumed says it was
	// picked up rather than created.
	SessionFile string
	Resumed     bool

	// Place is the session folder on THIS machine (session's place.go, Decision
	// 26). It is here for one reason: a picture arrives on this wire as bytes
	// and has to be written down before it can be journaled (image.go), and
	// where it lands is a question about the engine's disk that only the
	// engine's own session folder can answer. The zero Place is the legacy
	// layout. A pasted picture earns no row in the deliverables index — it is
	// the person's input, not something made for them — so the index path
	// itself is not carried here.
	Place session.Place
	// Note is the one sentence worth showing once: "session open elsewhere —
	// started a new one" travels here, the same words the local door puts on
	// the surface's entry notice.
	Note string
	// Launch is the shape this conversation was built with, echoed on every
	// welcome so a surface can tell the conversation it asked for from the one
	// it joined ([LaunchShape]). Nil is the engine's own defaults.
	Launch *LaunchShape

	// ApprovalMode is this machine's own answer to "does a tool run without
	// asking", read once at boot off the profile the boot closure resolved
	// against, and carried unchanged through a session swap (the profile
	// belongs to the machine, not to the file that happens to be open). It is
	// what turns the YOLO badge honest again over --host (host.go's approvalPosture,
	// tui3.go's ApprovalMode option).
	ApprovalMode string
	// BashBackgroundAfterSeconds is the foreground-command handoff clock this
	// engine armed. It travels for ApprovalMode's reason: a remote surface's
	// profile belongs to another machine, and zero is a meaningful off posture.
	BashBackgroundAfterSeconds int

	// Fresh builds a replacement agent on the same config with a new session
	// file, and returns it with that file's path. It is what Session.New calls,
	// and it is the local surface's /new closure by another name. Nil makes the
	// method fail rather than pretend.
	Fresh func() (WrappedAgent, string, error)

	// Open builds a replacement agent on the same config pointed at an existing
	// transcript, and says whether that file was found. It is Session.Open, and
	// it is the picker's Resume closure by another name.
	Open func(file string) (WrappedAgent, bool, error)

	// Recent lists the conversations this workspace has had. It is the one door
	// that exists only because the surface is remote: a local one reads the
	// session directory off its own disk, and a remote one cannot see it.
	Recent func() []session.Summary

	// StandingItems and StandingSave are this MACHINE'S ambient side, for the
	// same reason Recent is here: the store is a directory of documents under
	// the engine's own state root, a local surface opens it directly, and a
	// remote one has no way to. The workspace is a path on THIS disk, which is
	// the only kind of path an item's own Workspace field ever holds.
	//
	// Nil is the ambient side off for this engine, and it is answered as a
	// refusal rather than as an empty list — a capability that cannot work is
	// absent, and the surface keeps the difference between "no items" and "no
	// door" (internal/remote's Client.StandingItems says what it does with it).
	StandingItems func(workspace string) ([]standing.Item, error)
	// StandingSave writes one item back. THE STORE'S OWN REFUSAL IS THE ERROR:
	// internal/standing validates what it is asked to write, and a surface that
	// redrew a row as paused over a rejected write would be lying about this
	// disk, so nothing here softens it.
	StandingSave func(item standing.Item) error
	// StandingWatch reads this machine's scheduler. Nil means this engine has no
	// scheduler to ask, which the surface renders as no line.
	StandingWatch func() (standing.WatchStatus, bool)

	// World is the walk of this machine's places root: every project, every
	// conversation in it, and the work each of those ran. It is the reading five
	// of the surface's seven places are built from ([MethodPlacesWorld] names
	// them), which is why one door serves all five.
	World func() session.World

	// Ledger is the spend place's reading: the priced lines of THIS machine's
	// usage ledger at or after a floor the surface named, and whether the file
	// holds any priced line at all outside it ([LedgerReading] says why the
	// second fact cannot be derived from the first). Nil is a refusal, which the
	// surface draws as the sentence spend has always said.
	Ledger func(since time.Time) LedgerReading

	// Search is one full-text query over every message THIS machine has kept.
	// Nil is a refusal for the same reason, and it is the ordinary state of an
	// engine whose memory row is off: the index and the memory store are one
	// database today, and a machine that is not remembering has neither.
	Search func(terms string, limit int) ([]store.ConversationHit, error)

	// Memory is THIS machine's memory store, readings and writes together.
	//
	// IT IS ONE FIELD FOR SEVEN METHODS AND THAT IS THE POINT. The memory place
	// is the only place on the surface that WRITES, so a wire that carried its
	// readings and not its writes would hand a person a page of the far
	// machine's memories whose `e` and `f` keys edited this laptop's. The store
	// crosses whole or it does not cross, and nil is memory off over there —
	// which the surface says in those words rather than in this session's own
	// ([EngineMemory]).
	Memory  EngineMemory
	Archive func(dir string, archived bool) error
	// PlacesRoot is the directory World walked, carried on the welcome so the
	// surface can put THIS conversation back into a walk taken before it existed
	// ([Welcome.PlacesRoot] holds the argument). Empty says nothing about the
	// world door; a build that answers a world and no root simply cannot adopt.
	PlacesRoot string
	// TaskRecord is ONE ROW of that record read deeper than the walk reads it:
	// the last thing that piece of work said, out of the journal it left here
	// ([MethodPlacesTask]). nil is the same absence World's nil is — the door is
	// answered as a refusal and the card says so, rather than the surface reading
	// a path on its own disk that only exists on this one.
	TaskRecord func(uri string, tail int) (session.TaskRecord, error)
}

type EngineMemory interface {
	Snapshot(limit int) (store.MemoryShelves, error)
	ChangedSince(t time.Time) (learned, letGo int, err error)
	ListMemories(scope string, limit int) ([]store.Memory, error)
	UpdateMemory(id, title, text string, tags []string) error
	ForgetMemory(id string) error
	RestoreMemory(id string) error
	MemoryProvenance(id string) (sessionID, sessionTitle string, writtenAt time.Time, err error)
}

type EventWire struct {
	session.Event
	Err string `json:"Err,omitempty"`
}

type FactsPush struct {
	Rev   uint64        `json:"rev"`
	Facts session.Facts `json:"facts"`
}

type FetchFileArgs struct {
	Path string `json:"path"`
}

type FetchedFile struct {
	// Name is what the surface should call it when it writes it down. It is the
	// base name of the engine's path, and it is the engine's answer rather than
	// something this side derives, for the reason [WireFile.Name] states in the
	// other direction.
	Name string `json:"name"`
	MIME string `json:"mime,omitempty"`
	// Size and Hash describe the whole file the bytes came from. Hash is the
	// lowercase hex SHA-256 of Bytes — the same digest internal/cas keys on —
	// so a surface that caches by content can ask "do I already have this"
	// before it writes anything down.
	Size  int64  `json:"size,omitempty"`
	Hash  string `json:"hash,omitempty"`
	Bytes []byte `json:"bytes"`
}

type Following struct {
	// Said is the message that opened the turn, empty when the transcript
	// already has it — see [Turn.Said].
	Said string
	// Events is that turn, arriving.
	Events <-chan session.Event
}

type Frame struct {
	// Kind says what this frame is: "hello", "welcome", "call", "result",
	// "event", "closed", "facts", "task", "design", "question", "phase", "lane",
	// "turn", "driver", "moved", "fatal".
	//
	// "facts", "task", "design", "question", "phase" and "lane" are the KINDS
	// THAT ANSWER NOTHING. The third and fourth are version 11's harness lane
	// and version 14's questions lane, and each carries one [EventWire],
	// exactly as "task" does (standinglane.go); the last two carry the phase
	// clock and the lane sighting (news.go). Every other
	// frame from the engine either replies to a call or belongs to a stream a
	// call opened; these are the engine saying something the surface did
	// not ask for on that frame, because the whole point of them is that the
	// surface never has to ask. "facts" carries a [FactsPush]; "task" carries
	// one [EventWire] off the standing task lane (tasklane.go); "phase" carries
	// a [PhaseWire] and "lane" a [LaneWire], both off the news desk this engine
	// keeps for every conversation it is running (news.go). None of them has an
	// ID, and a build that does not know the kind ignores it, which is what the
	// reader in client.go already does with every kind it has no case for.
	Kind string `json:"kind"`
	// ID correlates a call with its result, and an event with the Submit that
	// opened its stream. The client mints call ids; the server mints stream ids
	// and names the stream in the call's result.
	ID uint64 `json:"id,omitempty"`
	// Method is the call's name, on "call" frames only — a [Method] constant.
	Method string `json:"method,omitempty"`
	// Payload is the frame's body, shaped by Kind and Method.
	Payload json.RawMessage `json:"payload,omitempty"`
	// Encoding and Data carry a large payload after both ends agreed on the
	// encoding at the version door. Payload stays the ordinary representation
	// so an older peer sees exactly the frames it has always seen; Data is only
	// emitted to a peer whose hello named this encoding.
	Encoding string `json:"encoding,omitempty"`
	Data     []byte `json:"data,omitempty"`
	// Error is a call that failed, on "result" frames, and the reason on
	// "fatal" frames.
	Error string `json:"error,omitempty"`

	// Seq is this event's position in its stream, counting from 1, on "event"
	// and "closed" frames only.
	//
	// IT EXISTS SO A REATTACH CAN ASK FOR THE GAP AND NOT FOR THE
	// CONVERSATION. A surface that dropped mid-turn has already drawn some of
	// that turn; the transcript door would give it the finished shape of what
	// it half-has, and the journal does not hold a partial reply's deltas at
	// all. So the engine keeps the turn's events in memory while it runs, the
	// returning surface says how far it got ([Hello.Resume]), and the engine
	// sends what came after. Numbering from 1 makes zero mean "nothing of this
	// stream has been seen", which is the state a surface attaching for the
	// first time is in.
	//
	// A "closed" frame carries the seq of the LAST event it follows, so a
	// surface can tell a stream that ended from one it lost the tail of.
	Seq uint64 `json:"seq,omitempty"`
}

type HarnessArgs struct {
	ID    uint64 `json:"id"`
	Run   bool   `json:"run"`
	Model string `json:"model,omitempty"`
}

type HeldQuestion struct {
	// Kind is which resolve-door answers this: "consent", "standing",
	// "harness", "connect". It is a string rather than an enum because the
	// envelope is the contract and a newer engine holding a kind this build
	// does not draw must not be a broken conversation — an unknown kind is
	// SKIPPED by the surface, which leaves the question waiting for a build
	// that knows it, exactly as it was.
	Kind string `json:"kind"`
	// Event is the frame that raised it, verbatim, so the surface draws the
	// card it would have drawn live.
	Event EventWire `json:"event"`
	// Stream is the turn it belongs to, so a surface reattaching mid-turn puts
	// the card back where it was rather than at the end of the room.
	Stream uint64 `json:"stream,omitempty"`
	// Since is when it was raised. THE SCREEN SHOULD SAY HOW LONG SOMETHING HAS
	// WAITED: a consent card from four hours ago is a different thing to answer
	// than one from four seconds ago, and only the engine knows which it is.
	Since time.Time `json:"since"`
}

type Hello struct {
	Version   int    `json:"version"`
	Workspace string `json:"workspace,omitempty"`
	// Session is an explicit session file to open, empty for the workspace's
	// latest-or-new (the same meaning the --session flag has locally).
	Session string `json:"session,omitempty"`

	// Model and Level are --model and --reasoning, carried in the frame that
	// BUILDS the session rather than applied to it a millisecond later.
	//
	// They retire a stub. Version 1 had no room for them, so the door set them
	// immediately after the handshake (cmd/codeaf's applyHostChoices), which
	// worked for every turn the person could type but left the session file's
	// first line naming the model the session was BORN on rather than the one
	// they asked for. Nobody on the screen could see the difference; the
	// journal could, and the journal is the record.
	Model string `json:"model,omitempty"`
	Level string `json:"level,omitempty"`

	// Launch is how the conversation should be BUILT, when this hello is the
	// one that opens it. Nil asks for the engine's own defaults, which is what
	// every remote surface sends: these are settings of the machine the session
	// runs on, and cmd/codeaf refuses them over --host and --at by name.
	Launch *LaunchShape `json:"launch,omitempty"`

	// Encodings are the optional frame payload encodings this surface can read.
	// They are negotiated INSIDE one protocol version because absence means the
	// old JSON payload and every added field is omitempty: an older engine
	// ignores this offer, and a newer engine sends it nothing encoded.
	Encodings []string `json:"encodings,omitempty"`

	// Resume is how far this surface got before it went away, one entry per
	// stream it still cares about. Empty is a surface that has seen nothing,
	// which is every first attach.
	//
	// THE ENGINE ANSWERS THE GAP AND NOTHING ELSE. Each cursor names a stream
	// and the last [Frame.Seq] this surface actually drew; the engine replays
	// from the one after it and then carries on live. A stream the engine no
	// longer holds — it finished long ago, or this is a different engine — is
	// answered with nothing rather than with an error: the transcript is the
	// authority on a finished turn, and the surface reads that anyway.
	Resume []StreamCursor `json:"resume,omitempty"`

	// Surface is this machine's short name — `macbook`, `spark` — as
	// [MachineName] reads it off os.Hostname.
	//
	// IT EXISTS SO A SCREEN CAN NAME THE WINDOW THAT HAS THE KEYBOARD. "somebody
	// else is typing" is a sentence that makes a person hunt; "typing from spark
	// now" is one they can act on, because they know where spark is. Two windows
	// on ONE machine send the same name, which is how the engine can tell the
	// far desk from the forgotten terminal behind this one.
	//
	// IT IS A LABEL AND NEVER AN IDENTITY. Nothing is authorized by it — a
	// connection is already whatever ssh or a pinned device key made it — and
	// the engine sanitizes it before it is drawn ([machineLabel]) because it is
	// text one machine sends for another machine's screen.
	Surface string `json:"surface,omitempty"`

	// Back says this surface has been in this conversation before and is coming
	// back from a link that dropped, rather than arriving for the first time.
	//
	// IT IS THE ONE THING THAT KEEPS "THE NEWEST WINDOW DRIVES" HONEST. A redial
	// is an attach the person did not make: they closed a laptop lid in one city
	// and started typing in another, and the lid's machine reconnecting in the
	// background half an hour later must not take the keyboard off the machine
	// they are sitting at. So a returning surface drives only if the keyboard is
	// going spare, and a NEW one always drives.
	Back bool `json:"back,omitempty"`

	// Join says this hello wants a conversation THAT IS ALREADY OPEN and will
	// take nothing else. [Session] names the transcript to look for, and a host
	// that is not running it answers an error rather than starting it.
	//
	// IT EXISTS BECAUSE "OPEN OR CREATE" IS THE WRONG VERB FOR A SECOND VIEW. A
	// surface that wants to READ one task of a conversation running next door is
	// asking about work that exists; booting a whole session so that the question
	// has an answer would start a model, take the transcript's lock away from
	// nobody, and hand back a conversation with none of the work in it. So the
	// two intentions are two flags rather than one hopeful one.
	//
	// AND IT IS MATCHED ON THE TRANSCRIPT AND NOT ON THE KEY. A host keys its
	// conversations by whatever the FIRST hello said — which for the ordinary
	// launch is the empty string, meaning "this workspace's latest" — so a second
	// surface naming the same conversation by its file would miss it and be given
	// a new one. The file is the identity every other part of this program uses
	// for a conversation, so it is the one a join is answered on.
	Join bool `json:"join,omitempty"`

	// New says this hello MINTS A CONVERSATION OF ITS OWN and will not be given
	// one that is already open. It is the exact opposite of [Join], and the two
	// are separate flags for the same reason Join is separate from an ordinary
	// hello: "open or create" is the wrong verb for both intentions.
	//
	// IT IS WHAT MAKES A SECOND TAB A SECOND CONVERSATION. An ordinary hello
	// naming no session means "this workspace's latest-or-new", so two surfaces
	// that both say nothing are asking for the SAME conversation — which is the
	// whole of "sit down somewhere else and be in it" and exactly wrong for a
	// window opening another chat beside the one it already has. Without this
	// flag the only way to mint one was [MethodSessionNew], which SWAPS the
	// conversation on the connection that asked and ends the one it replaced
	// (internal/remote's Session.swap): one connection, one conversation, and the
	// sentence a person read on screen.
	//
	// THE ENGINE CHOOSES THE FILE. This hello carries no session, because the
	// transcript a new conversation lands on is a question about the engine's own
	// disk; the welcome names what it opened, and a host keys the conversation by
	// that answer so a later window can name it and join.
	//
	// A REDIAL NEVER SAYS IT TWICE. [Client.helloNow] clears it once a welcome is
	// in hand, alongside the session and [Back] it already rewrites — a link that
	// dropped is coming back to the conversation it minted, not asking for
	// another one.
	New bool `json:"new,omitempty"`

	// Watch says this surface is HERE TO READ and must never be given the
	// keyboard — not on arrival, not when the driver leaves, not ever.
	//
	// [Back] IS NOT THIS, and reading it as this is the bug that made the flag
	// necessary. A returning surface takes the keyboard when it is going spare,
	// which is right for a redial and wrong for a second view somebody opened to
	// look at one piece of work: the window that owns the conversation may simply
	// have detached for a moment, and it would come back to find a reader driving
	// it. A watcher is refused the keyboard even when there is no driver at all,
	// so the conversation is left with none rather than with the wrong one.
	//
	// IT IS THE SURFACE'S OWN DECLARATION AND THE ENGINE STILL DECIDES. Nothing
	// here is a permission — the engine enforces it, in the one place that owns
	// who drives (driver.go) — and a watcher that tries to type anyway is refused
	// with a sentence rather than dropped.
	Watch bool `json:"watch,omitempty"`
}

type HostSelf struct {
	// Version is the protocol this build speaks — [Version], filled in by the
	// answering side rather than by whoever built the struct, because ONE
	// SOURCE OF TRUTH about a build's protocol is the constant compiled into
	// it.
	Version int `json:"version"`
	// Build identifies the running executable even when its protocol is unchanged.
	// It is the source the executable was built from, so rebuilding the same commit
	// answers with the same word and only a real source change reads as another
	// build. An empty stamp identifies a host predating this check, not a matching
	// build.
	Build string `json:"build,omitempty"`
	// Busy is work in flight: a surface attached, a turn running, or a question
	// waiting for somebody to come back and answer it.
	Busy bool `json:"busy,omitempty"`
	// Retiring says the host took the stand-down and is on its way out. The
	// asker waits for the socket to stop answering and then starts a fresh one.
	Retiring bool `json:"retiring,omitempty"`
	// Workspace is the directory this host holds, for a sentence that has to
	// name it.
	Workspace string `json:"workspace,omitempty"`
}

type InterruptArgs struct {
	Door string `json:"door,omitempty"`
}

type LaneWire struct {
	// Model is the model the answer came back on. A news with no model belongs
	// to nobody and is dropped on both sides of the wire.
	Model string `json:"model"`
	// Lane is the machine the request WENT TO and Winner the one that finished
	// it; they differ only when a rescue landed, which is the whole of what a
	// surface means by "rescued". Alt is whichever of the pair was not asked
	// first.
	Lane   string `json:"lane,omitempty"`
	Alt    string `json:"alt,omitempty"`
	Winner string `json:"winner,omitempty"`
	// TTFTMS is the wait before the first token in milliseconds, and Rate how
	// fast the answer was written.
	TTFTMS int64   `json:"ttftMs,omitempty"`
	Rate   float64 `json:"rate,omitempty"`
	// Hedged says a second request went out for this answer; Trying says one is
	// out RIGHT NOW and nobody has committed yet.
	Hedged bool `json:"hedged,omitempty"`
	Trying bool `json:"trying,omitempty"`
	// Reason is why the rescue went out, in the transport's own two words, and
	// Failed WITHDRAWS a claim already made: the lane in Alt was what a
	// `trying X…` was about and it has now failed.
	Reason string `json:"reason,omitempty"`
	Failed bool   `json:"failed,omitempty"`
	// Role is who the answer was for. It crosses unfiltered for [PhaseWire.Role]'s
	// reason.
	Role string `json:"role,omitempty"`
	// Subject is which piece of work the sighting is about, and it crosses for
	// [PhaseWire.Subject]'s reason and with its reading of absence: empty is the
	// conversation. It is spelled the same on both wire shapes because they are
	// twins, and a surface keys both desks with one function.
	Subject string `json:"subject,omitempty"`
	// Session is whose sighting it is, for [PhaseWire.Session]'s reason and with
	// its reading of absence: an older peer sends none, and the sighting is
	// filed under its model as it always was.
	Session string `json:"session,omitempty"`
}

type Lanes struct {
	// Designs is the harness lane (standinglane.go): the design card, the notes
	// around it, and the subharness intake card that shares the subscription. It
	// is complete — the events cross, ResolveHarness has answered the design
	// card since version 1, and internal/session replays a card that is still
	// standing onto every new subscription, so a detached window comes back to
	// it.
	Designs bool
	// Cards is the intake card's own answer door, [MethodSubharnessResolve]. It
	// is a separate bit because the two cards share a subscription and not an
	// answer.
	Cards bool
	// Runs is the adaptive run lane, and it is FALSE in this build. The work
	// that is left is exact:
	//
	//  1. internal/session's WatchOrchestrations replays nothing, unlike
	//     WatchHarnessDesigns. A run's fuel gate raised while every window is
	//     away would be lost on reconnect, and a gate nobody can answer stops
	//     the run in silence at its cap.
	//  2. internal/tui3's orchAgent needs four doors, not one. Snapshot and
	//     SteerOrchestrate would cross as they stand; OrchestrateNodeJournal
	//     answers a PATH ON THE ENGINE'S DISK, which the run page reads locally
	//     (roomorch.go's session.ReadTranscript), so it needs a content-carrying
	//     door and a seam in that package before it can be honest here.
	//
	// Nothing is lost by the wait: no command, tool or cue opens an adaptive run
	// in this build, on this machine or a far one, so a conversation built
	// without the runner is the same conversation either way.
	Runs bool
}

type LaunchShape struct {
	Yolo      bool    `json:"yolo,omitempty"`
	NoCompact bool    `json:"noCompact,omitempty"`
	OneModel  bool    `json:"oneModel,omitempty"`
	MaxHours  float64 `json:"maxHours,omitempty"`
	MaxCost   float64 `json:"maxCost,omitempty"`
	// Interactive says the surface that opened this conversation is a screen
	// somebody is typing into, so the session is steered rather than run to a
	// goal of its own. Only the local dial fills it; a --once probe leaves it
	// unset, and the engine maps it onto the session's own steering fact.
	Interactive bool `json:"interactive,omitempty"`
}

type LedgerArgs struct {
	Since time.Time `json:"since,omitempty"`
}

type LedgerReading struct {
	// Lines are every priced call at or after [LedgerArgs.Since], in the order
	// the ledger holds them.
	Lines []session.UsageLine `json:"lines,omitempty"`
	// Held is whether the ledger holds ANY priced line at all, at any depth —
	// the fact that tells a machine which has never spent anything from a window
	// paged onto a quiet fortnight. The spend page draws its own three sentences
	// for the first and the window header over nothing for the second
	// (internal/tui3's [spendPage.held]), and a bounded read cannot tell them
	// apart on its own: no lines since a floor is both.
	Held bool `json:"held,omitempty"`
}

type ListDirArgs struct {
	Path string `json:"path"`
}

type Loop struct {
	// Client is the surface's half — the real [Client], dialled and handshaken.
	Client *Client
	// Served is the error [Serve] finished with, readable after Close. It is a
	// channel rather than a field because the engine goroutine outlives the
	// call that started it, and a test that wants to know how the far end died
	// has to be able to wait for it.
	Served <-chan error
	// contains filtered or unexported fields
}

type MemoryChange struct {
	Learned int `json:"learned,omitempty"`
	LetGo   int `json:"letGo,omitempty"`
}

type MemoryListArgs struct {
	Scope string `json:"scope,omitempty"`
	Limit int    `json:"limit,omitempty"`
}

type MemoryOrigin struct {
	Session string    `json:"session,omitempty"`
	Title   string    `json:"title,omitempty"`
	At      time.Time `json:"at,omitempty"`
}

type MemoryUpdateArgs struct {
	ID    string   `json:"id"`
	Title string   `json:"title,omitempty"`
	Text  string   `json:"text,omitempty"`
	Tags  []string `json:"tags,omitempty"`
}

type Moved struct {
	// Machine is the arriving surface's machine name as [Hello.Surface] gave
	// it, sanitized ([machineLabel]) because it is drawn. Empty is a surface
	// that sent none.
	Machine string `json:"machine,omitempty"`
	// Here says the window that took it is on THIS surface's own machine.
	Here bool `json:"here,omitempty"`
}

type Options struct {
	Boot func(Hello) (*Engine, error)
}

type PathFact struct {
	Path   string `json:"path"`
	Exists bool   `json:"exists,omitempty"`
	Dir    bool   `json:"dir,omitempty"`
	// Size is the file's byte count as this machine sees it. A directory
	// reports its own, which is a filesystem artifact rather than a fact about
	// what is inside it — the surface reads it for files and nothing else.
	Size int64 `json:"size,omitempty"`
	// ModTime is the last modification in whole seconds since the epoch, which
	// is the resolution every filesystem and every archive format agrees on.
	// It is a NUMBER and not a time.Time because it is compared and never
	// drawn: a surface asking "is this the file I already have" wants equality,
	// not a moment in a person's timezone.
	ModTime int64 `json:"mtime,omitempty"`
}

type PhaseWire struct {
	// Phase is [provider.Phase] — the person's own word for what is happening.
	// An empty phase is the end of the story and is carried as such, because a
	// stale clock left running is the defect the phase seam exists to fix.
	Phase string `json:"phase,omitempty"`
	// Model is the model this request is on and Role who it is for
	// ([lane.Role]). EVERY ROLE CROSSES AND THE SURFACE DECIDES: a task node's
	// phases are drawn where a node is drawn and a conversation's on the status
	// row, and that filter is already written on the surface (internal/tui3's
	// phase.go). An engine that filtered here would be a second opinion about
	// the same question.
	Model string `json:"model,omitempty"`
	Role  string `json:"role,omitempty"`
	// Subject is which piece of work this news is about: empty for the
	// conversation, and one node's own name for a node
	// ([session.NewsSubject]). AN OLDER PEER SENDS NONE, WHICH READS AS THE
	// CONVERSATION — the same absence every producer that predates the field
	// means, so a surface talking to a build without it behaves exactly as it
	// always did.
	Subject string `json:"subject,omitempty"`
	// Session is WHOSE news this is — the conversation, in the engine's own
	// spelling ([session.Agent.NewsKey]) — and the name the surface files the
	// conversation's own news under first (internal/tui3's newsDeskKeys).
	//
	// IT CROSSES BECAUSE THE MODEL IS NOT AN IDENTITY. Without it the surface
	// filed the conversation's phases under the model id, and the model is
	// exactly the thing that moves between an engine and a window: a pick made
	// mid-turn, a stream-cut hop onto another model, a change made from another
	// window. Each put the live rate and the machine under a name that window
	// was not asking for.
	//
	// AN OLDER PEER SENDS NONE, and the surface files what it gets under the
	// model alone, which is what it always did — so no version moves for it.
	Session string `json:"session,omitempty"`
	// Lane is the machine answering when one has named itself, and Rate how
	// fast it is writing in tokens a second. Zero for both is "not measured",
	// never "nothing" — the emptiness law, carried across the wire intact.
	Lane string  `json:"lane,omitempty"`
	Rate float64 `json:"rate,omitempty"`
	// Door is the billing road in use. It stays separate from Lane so a direct
	// service is never presented as a router's serving machine.
	Door string `json:"door,omitempty"`
	// Detail is the phase's own noun, already in a person's words, and Then
	// what will be done about the wait when a deadline is real.
	Detail string `json:"detail,omitempty"`
	Then   string `json:"then,omitempty"`
	// SinceMS is how long this phase had lasted when the engine said so, and
	// DeadlineMS how long was left before something is done about it. Both in
	// milliseconds; zero DeadlineMS is no deadline, which is the honest answer
	// wherever no alternative lane exists.
	SinceMS    int64 `json:"sinceMs,omitempty"`
	DeadlineMS int64 `json:"deadlineMs,omitempty"`
}

type PlacesTaskArgs struct {
	Transcript string `json:"transcript"`
	Tail       int    `json:"tail,omitempty"`
}

type PlannerStartArgs struct {
	Brief string `json:"brief"`
	Hint  string `json:"hint,omitempty"`
}

type PlannerStarted struct {
	ID    string `json:"id,omitempty"`
	Title string `json:"title,omitempty"`
}

type QuestionArgs struct {
	Answer session.Answer `json:"answer"`
}

type QuestionHoldArgs struct {
	Kind  session.QuestionKind `json:"kind"`
	Token string               `json:"token"`
}

type ReasoningArgs struct {
	Model string `json:"model"`
	Level string `json:"level"`
}

type ReferArgs struct {
	Path    string               `json:"path"`
	Arrival session.PlaceArrival `json:"arrival,omitempty"`
}

type Refusal struct{ Reason string }

type Roaming struct {
	// Dial opens the next link. Required.
	Dial Dialer
	// Window is how long to keep trying, and zero is [RoamWindow].
	Window time.Duration
}

type SearchArgs struct {
	Terms string `json:"terms"`
	Limit int    `json:"limit,omitempty"`
}

type Session struct {
	// contains filtered or unexported fields
}

type StandingArgs struct {
	ID     uint64                 `json:"id"`
	Answer session.StandingAnswer `json:"answer"`
}

type StandingWatchResult struct {
	Status standing.WatchStatus `json:"status"`
	Known  bool                 `json:"known"`
}

type StatPathsArgs struct {
	Paths []string `json:"paths"`
}

type StreamCursor struct {
	Stream uint64 `json:"stream"`
	Seq    uint64 `json:"seq"`
}

type StreamRef struct {
	Stream uint64 `json:"stream"`
}

type SubharnessResolveArgs struct {
	ID    uint64          `json:"id"`
	Run   bool            `json:"run"`
	Input json.RawMessage `json:"input,omitempty"`
}

type SubmitArgs struct {
	Text string `json:"text"`
	// Standing says the person MARKED this draft as something to keep true
	// (internal/session's standing_mark.go), so the engine opens the turn
	// through SubmitStanding rather than Submit.
	//
	// IT IS A FIELD RATHER THAN A METHOD OF ITS OWN because the two differ in
	// what the engine puts in front of the sentence and in nothing a wire can
	// see: same argument, same StreamRef, same event frames. An older engine
	// that does not read it runs the ordinary turn, which is the one direction
	// this may fail in that leaves the person's words intact.
	Standing bool `json:"standing,omitempty"`
}

type SubmitFilesArgs struct {
	Text  string     `json:"text"`
	Files []WireFile `json:"files"`
	// Images ride along so ONE MESSAGE IS ONE CALL. A person who pastes a
	// screenshot and drops a log file has sent one message, and splitting it
	// into two submits would open two turns.
	Images []session.Image `json:"images,omitempty"`
}

type SubmitImageArgs struct {
	Text   string          `json:"text"`
	Images []session.Image `json:"images"`
}

type TaskHoldArgs struct {
	ID uint64 `json:"id"`
}

type TaskPending struct {
	IDs []uint64 `json:"ids"`
}

type TaskResolveArgs struct {
	ID       uint64 `json:"id"`
	Approved bool   `json:"approved,omitempty"`
	Redirect string `json:"redirect,omitempty"`
	Model    string `json:"model,omitempty"`
}

type TaskRoomArgs struct {
	ID   uint64 `json:"id"`
	Tail int    `json:"tail,omitempty"`
}

type TaskSettleArgs struct {
	ID uint64 `json:"id"`
	// Merge spends one more merge round on a branch that clashed. It is the
	// conflict card's yes, and it takes nothing as done.
	Merge bool `json:"merge,omitempty"`
	// Hand gives this one decision to the model. Back takes it away again.
	Hand bool `json:"hand,omitempty"`
	Back bool `json:"back,omitempty"`
	// Resolution is `accept`, `reaudit` or `refute` — [session.TaskResolution] as
	// it crosses — and Why is the sentence a caller may put on the record with it.
	Resolution string `json:"resolution,omitempty"`
	Why        string `json:"why,omitempty"`
}

type TaskSettled struct {
	Decided bool `json:"decided,omitempty"`
}

type TaskSetupArgs struct {
	ID      uint64 `json:"id"`
	Session string `json:"session"`
	Value   string `json:"value,omitempty"`
}

type TaskStartArgs struct {
	Brief string `json:"brief"`
	Solo  bool   `json:"solo,omitempty"`
}

type TaskStarted struct {
	ID    uint64 `json:"id,omitempty"`
	Title string `json:"title,omitempty"`
	Note  string `json:"note,omitempty"`
}

type TaskSteerArgs struct {
	ID   uint64 `json:"id"`
	Text string `json:"text"`
	// Scope and Seq are the send's identity, absent on a surface that has no way
	// to mint one and on every client written before this.
	Scope string `json:"scope,omitempty"`
	Seq   uint64 `json:"seq,omitempty"`
	// Said is when the person pressed enter, which is what the node's record
	// orders its corrections by. It travels because a send may be repeated
	// minutes later and the instant that decides which correction is the later
	// one is the one they said it at, not the one the wire delivered it on.
	Said time.Time `json:"said,omitzero"`
	// Session is the conversation the surface believed it was addressing, and it
	// is checked at the engine against the one actually open.
	//
	// THE HANDLE DOES NOT CHANGE WHEN THE CONVERSATION DOES. `Session.Open` and
	// `Session.New` swap the engine's conversation behind the same client and the
	// same agent (cmd/codeaf's chatv3_host.go returns that agent unchanged), so a
	// send held over a swap — queued behind another, or retried after one — would
	// otherwise reach whatever task 7 means in the conversation that replaced it.
	// Empty is a surface making no claim.
	Session string `json:"session,omitempty"`
}

type TaskSteered struct {
	Waiting   bool   `json:"waiting,omitempty"`
	Held      bool   `json:"held,omitempty"`
	Direction uint64 `json:"direction,omitempty"`
	Landing   string `json:"landing,omitempty"`
	// Again says this node already held these words FROM THIS SAME SEND, so
	// nothing was delivered a second time and Direction is the receipt the first
	// one was written down as. It is the answer a surface asking again for a
	// crossing nobody answered is hoping for, and it is why asking again is safe
	// at all ([TaskSteerArgs]).
	Again bool `json:"again,omitempty"`
	// Elsewhere says the conversation the surface named ([TaskSteerArgs.Session])
	// is not the one open here, so NOTHING WAS DELIVERED. It is a field rather
	// than an error string because the surface has to recognise it exactly: the
	// send stays unresolved and is never re-aimed at the task with that number in
	// the conversation that replaced it (internal/session's
	// [session.ErrNotThatConversation]).
	Elsewhere bool `json:"elsewhere,omitempty"`
	// Uncertain says the engine could not tell whether this correction was kept:
	// it reached the record and could not be taken back off the disk again
	// (internal/session's [session.ErrSendUnanswered] wearing an engine's reason
	// rather than a dead link's). It is a field for [Elsewhere]'s reason — the
	// surface has to recognise it exactly, keep the send under the name it has,
	// and offer to ask again rather than hand the words back to be renamed.
	Uncertain bool `json:"uncertain,omitempty"`
}

type TaskStopArgs struct {
	ID string `json:"id"`
}

type TaskStopped struct {
	Line string `json:"line,omitempty"`
}

type Turn struct {
	Stream uint64 `json:"stream"`
	Said   string `json:"said,omitempty"`
}

type Welcome struct {
	Version     int    `json:"version"`
	Workspace   string `json:"workspace"`
	SessionFile string `json:"sessionFile"`
	Resumed     bool   `json:"resumed"`
	Model       string `json:"model"`
	Build       string `json:"build,omitempty"`
	Title       string `json:"title,omitempty"`
	ShortTitle  string `json:"shortTitle,omitempty"`
	// Note is a sentence worth showing once — "session open elsewhere, started
	// a new one" travels here.
	Note string `json:"note,omitempty"`
	// ApprovalMode is the engine machine's own answer to "does a tool run
	// without asking" (internal/config's ToolApprovalModeAt) — "allow" or
	// empty. A REMOTE YOLO BADGE MUST NAME THE ENGINE'S POSTURE, NOT THIS
	// LAPTOP'S: the gate that decides whether a tool runs unattended is read
	// from the profile on the machine that runs it, and drawing the badge from
	// the surface's own settings would be a safety claim about a machine
	// nobody consulted.
	ApprovalMode string `json:"approvalMode,omitempty"`
	// BashBackgroundAfterSeconds is the foreground-command clock the ENGINE
	// armed for this session. A HOSTED COUNTDOWN MUST READ THIS MACHINE'S
	// POSTURE, NOT THE SURFACE'S PROFILE: zero is a real off answer, so absence
	// cannot be filled from a local default without inventing a deadline.
	BashBackgroundAfterSeconds int `json:"bashBackgroundAfterSeconds,omitempty"`
	// ProfileDir is the engine process's resolved profile directory. A plain
	// linked-local surface uses it for writes because the daemon may predate the
	// terminal's current profile override. An older peer sends none and the
	// surface falls back to its own resolved directory; linked-local launches
	// retire a daemon whose build differs, so that compatibility reading is
	// theoretical on the road that consumes it. No protocol version moves.
	ProfileDir string `json:"profileDir,omitempty"`
	// Encoding is the one frame payload encoding selected from Hello.Encodings,
	// or empty when this connection stays on ordinary JSON payloads.
	Encoding string `json:"encoding,omitempty"`

	// PlacesRoot is the engine machine's own state root — the directory
	// [MethodPlacesWorld] walked, on the disk it walked it on.
	//
	// IT TRAVELS BECAUSE A WORLD IS A SET OF PATHS AND A PATH NEEDS ITS DISK.
	// [session.World.Adopt] puts the conversation THIS WINDOW is sitting in back
	// into a walk that was taken too early to see it, and it needs the root that
	// walk was taken under to work out which bucket the conversation belongs to.
	// Handing it this laptop's root would file a session that lives on the server
	// under a project on the laptop. Empty is an engine that answers no world,
	// which is version 3 and every build before it.
	PlacesRoot string `json:"placesRoot,omitempty"`

	// Live is the stream still running when this surface arrived, or zero.
	//
	// IT IS THE WHOLE POINT OF THE PERSISTENT ENGINE, said in one number: a
	// person asked for a long refactor from a café, closed the laptop, and sat
	// down somewhere else — and this field is how the new surface learns there
	// is a turn in flight to reattach to rather than an idle session to type
	// at. The events of that turn arrive as ordinary "event" frames from
	// [Hello.Resume]'s cursor onward, so nothing about drawing it is special.
	Live uint64 `json:"live,omitempty"`

	// Attached is how many OTHER surfaces are on this session right now.
	//
	// It is carried because a surface that is not alone must be able to say so:
	// two people (or one person and their own forgotten window) sharing a
	// conversation is a fact about that conversation, and a screen that hid it
	// would be the one place codeaf lied about who is in the room. Zero is the
	// ordinary case and draws nothing, by the emptiness law.
	Attached int `json:"attached,omitempty"`

	// Held is the questions this session raised while nobody was attached,
	// carried in the welcome so the first frame a returning surface draws
	// already has them. See [HeldQuestion].
	Held []HeldQuestion `json:"held,omitempty"`

	// Facts is the fact set this surface arrives holding — the model, the name,
	// the spending, the weight, the reasoning levels — so the FIRST frame it
	// draws is drawn from memory and not from four round trips.
	//
	// It is a pointer so that "this engine states nothing" is a thing a decoder
	// can see. Nothing on the surface has to handle that case today (the door
	// refuses a version mismatch before the screen exists), but a nil here and a
	// zero-valued fact set are different facts, and a replica filled from the
	// second would draw a conversation with no model and nothing spent.
	Facts *FactsPush `json:"facts,omitempty"`

	// Persistent says the far end is a session HOST — the engine outlives this
	// connection — rather than version 2's other honest shape, a one-shot
	// engine on a pipe.
	//
	// A SURFACE MUST NOT PROMISE A LIFETIME THE ENGINE DOES NOT HAVE. Both
	// shapes speak this protocol and both are legitimate: `codeaf engine`
	// started by hand on a machine with no host is still a conversation, it
	// simply ends when the pipe does. The screen's word for detaching, and
	// whether "close the lid, it keeps going" is true, both hang off this
	// single fact, so it is stated rather than assumed from the transport.
	Persistent bool `json:"persistent,omitempty"`

	// Launch is the shape the conversation actually has, as the engine built
	// it. It is an ECHO and not a confirmation: a hello that asked for one
	// shape and joined a conversation somebody else had already opened gets
	// that conversation's shape here, and the surface is expected to notice.
	Launch *LaunchShape `json:"launch,omitempty"`

	// Driver is who holds the keyboard the moment this surface arrived, told
	// the way this surface should read it. A first attach is always the driver;
	// a [Hello.Back] one may not be.
	//
	// IT IS CARRIED ON THE WELCOME AND NOT LEFT TO THE FIRST "driver" FRAME,
	// because a frame is only sent when the answer CHANGES and a returning
	// surface can arrive into an answer that did not. A surface that assumed it
	// drove until told otherwise would draw a composer somebody's keystrokes
	// would then be refused into.
	Driver Driver `json:"driver,omitzero"`

	// SteerRepeat says this engine RECOGNISES A SEND IT HAS ALREADY TAKEN: a
	// correction sent into a task's page again under the same identity
	// ([TaskSteerArgs]) answers the receipt already on the record and delivers
	// nothing.
	//
	// IT IS CARRIED BECAUSE THE QUESTION IS ASKED BEFORE ANYTHING IS SENT, and
	// it has to be. A surface holding a send it got no answer to has exactly two
	// moves — ask again, or keep the words and say so — and which one is honest
	// depends on a fact about the far machine that no failed call can report:
	// the call that would have told it is the one that stopped answering.
	//
	// ABSENCE IS false AND false IS THE SAFE READING. An engine that predates
	// this ignores the identity on a send, so a repeat there would be a second
	// correction; the surface therefore keeps the person's words instead of
	// asking twice, which is the degradation that costs a keystroke rather than
	// the one that corrects a worker twice.
	SteerRepeat bool `json:"steerRepeat,omitempty"`

	// SteerOwner says this engine CHECKS THE CONVERSATION A SEND WAS WRITTEN FOR
	// ([TaskSteerArgs.Session]) against the one it actually has open, and refuses
	// rather than delivering to the task with that number over here.
	//
	// IT IS A SEPARATE FACT FROM SteerRepeat and may not be inferred from it: an
	// engine can keep send identities and still have been built before this check
	// existed, and it would then read Session as an unknown field and deliver.
	//
	// ABSENCE IS false, AND false MEANS THE SURFACE MUST NOT SEND A BOUND
	// CORRECTION AT ALL. An unenforced claim is worse than no claim: the surface
	// would believe the engine was guarding something nobody is guarding.
	SteerOwner bool `json:"steerOwner,omitempty"`
	// TaskSetup advertises task-scoped model and thinking controls.
	TaskSetup bool `json:"taskSetup,omitempty"`
	// TaskSettle says this engine can be ASKED TO DECIDE A LANDING — accept, not
	// right, one more merge round, the hand-over and the take-back
	// ([MethodTaskSettle]).
	//
	// IT IS CARRIED FOR [Welcome.Folders]'S REASON, and the cost of not carrying
	// it was measured: internal/tui3 asserts these doors on the agent it holds and
	// draws no answers row at all where the assertion fails, so a window on an
	// engine host drew a landing card with its reason and nothing to press (#706).
	// Every *Agent has the methods; only the welcome knows whether the machine at
	// the far end does.
	TaskSettle bool `json:"taskSettle,omitempty"`

	// Effort says this engine HAS A DIAL ON THE CONVERSATION'S OWN THINKING —
	// that its agent answers [MethodEffort], [MethodResolvedEffort] and
	// [MethodSetEffort] rather than refusing them (effort.go).
	//
	// IT IS CARRIED FOR [Welcome.Folders]'S REASON, WHICH IS THE ONE THAT MATTERS
	// MOST HERE. A surface at this end holds a *remote.Agent, which ALWAYS has
	// the three methods on it, so the type assertion a local surface uses to tell
	// a dial from no dial answers yes for every connection and says nothing about
	// the far machine. And the honest reading cannot be taken from the ANSWER
	// either: "" is a real rung on this ladder — a conversation asking for no
	// thinking at all — so silence and absence are the same string, and the flag
	// is the only thing that separates them.
	//
	// ABSENCE IS false AND false IS THE SAFE READING: A CAPABILITY THAT CANNOT
	// WORK IS ABSENT, NOT BROKEN, so the seam draws no rung, the chord does
	// nothing, and nothing on the screen offers to move a knob the far engine
	// has never heard of.
	Effort bool `json:"effort,omitempty"`

	// Folders says this engine CAN HOLD THE FOLDERS A CONVERSATION IS ABOUT —
	// that its agent answers [MethodPlacesRefer] and [MethodPlacesRemove] rather
	// than refusing them (wire_places.go).
	//
	// IT IS CARRIED BECAUSE THE QUESTION IS ASKED BEFORE ANYTHING IS CHOSEN, and
	// that is [Welcome.SteerRepeat]'s reason exactly. A surface at this end holds
	// a *remote.Agent, which ALWAYS has the three methods on it — so the type
	// assertion a local surface uses to tell a capable agent from an incapable
	// one answers yes for every connection and says nothing about the machine at
	// the far end. Without this flag the only honest reading arrives as the
	// refusal to the call, which is after the person has already picked a folder
	// out of a list and pressed enter.
	//
	// ABSENCE IS false AND false IS THE SAFE READING: an engine that predates
	// these doors sends no field, and a surface that believed it could attach
	// would open a picker whose every row ends in an error.
	Folders bool `json:"folders,omitempty"`

	// News says this engine SENDS THE STATUS LINE'S NEWS — the "phase" and
	// "lane" frames the live rate and the `via <machine>` rider are drawn from
	// (news.go) — for the conversation this surface arrived in.
	//
	// IT MAKES AN ABSENCE KNOWABLE WITHOUT REFUSING ANYBODY. The news frames
	// rode an existing version on purpose ([Version]'s note says why: a status
	// line must not turn a live conversation away), which left a surface
	// attached to an engine from before them drawing no rate and no machine and
	// no way to say why — and a busy older engine on the same version is
	// attached to rather than retired (cmd/codeaf's clearStaleEngineHost). A
	// surface reads this, or a news frame arriving, as the engine having the
	// news; neither after a whole answer is an older engine, and the surface
	// says so once ([Client.NewsSilent]).
	//
	// ABSENCE IS false, and it is not by itself proof of an old engine: every
	// build between the news frames and this flag sends them without saying so,
	// which is why a frame arriving counts as the same answer.
	News bool `json:"news,omitempty"`
}

type WhoIs struct {
	// StandDown asks the host to retire: close its conversations, flush their
	// journals, drop the socket and exit, so the next connection starts a host
	// from whatever binary is on disk now. It is refused while there is work in
	// flight, and the answer says which happened.
	StandDown bool `json:"standDown,omitempty"`
	// Anyway asks for the retirement even with work in flight, and there is
	// exactly one caller: a person typing `codeaf engine --stop` on the machine
	// itself, who has been told what is running and said stop anyway. A turn
	// caught by it stops where it is and keeps its partial reply — the same
	// thing ctrl+c does locally, by the same road ([Session.Close]).
	Anyway bool `json:"anyway,omitempty"`
}

type WireFile struct {
	// Name is the file's own name as the surface saw it, and NEVER a path: the
	// engine joins it to a directory of the engine's choosing, so a "name" that
	// walked out of that directory would be this wire handing a remote machine
	// an arbitrary write. The engine sanitizes it regardless — a boundary that
	// trusts its input is not a boundary — but the field is documented as a
	// name so that nothing on this side is tempted to send a path.
	Name string `json:"name"`
	// MIME is what the surface believed this was, empty when it could not tell.
	// It is a hint for the engine's naming and nothing is refused for lacking
	// it — unlike an image, whose type the provider genuinely needs.
	MIME string `json:"mime,omitempty"`
	// Bytes is the file itself. The frame ceiling (server.go's frameCap) is the
	// only limit this wire imposes; the SIZE the person is allowed to attach is
	// a surface question, asked on the surface, in the surface's own words —
	// the same division images already use.
	Bytes []byte `json:"bytes"`
}

type WrappedAgent interface {
	Submit(ctx context.Context, text string) (<-chan session.Event, error)
	SubmitStanding(ctx context.Context, text string) (<-chan session.Event, error)
	SubmitImage(ctx context.Context, text string, images []session.Image) (<-chan session.Event, error)
	FollowUp(text string) (<-chan session.Event, error)
	Steer(text string) (<-chan session.Event, error)
	Interrupt()
	// InterruptFor is the stop with the door it came through on it, for the
	// machinery stops that are not a person (internal/session's stopcause.go).
	InterruptFor(door session.StopDoor)
	Compact(ctx context.Context) error
	Close() error
	Model() string
	SetModel(model string)
	SetContextWindow(tokens int)
	ReasoningFor(model string) string
	// ReasoningLevels is every model somebody has dialled and the level it
	// holds. It is here rather than left to ReasoningFor above because a
	// SURFACE ASKS THAT QUESTION ABOUT MODELS IT HAS NOT SWITCHED TO — a picker
	// row, a ctrl+t on that row — and one round trip per row is exactly the
	// shape [session.Facts] exists to end. The whole map is a handful of short
	// strings and travels in one push.
	ReasoningLevels() map[string]string
	SetReasoningFor(model, level string)
	ResolveConsent(id uint64, allow bool)
	ResolveConsentRemember(id uint64, allow bool, scope session.ConsentScope)
	ResolveStanding(id uint64, answer session.StandingAnswer)
	ResolveHarness(id uint64, run bool, model string)
	ResolveConnect(id string, approve bool)
	ResolveConnectKey(id string, key string)
	NoteConnected(service, account string)
	Title() string
	Usage() session.Usage
	ContextTokens() int
	Transcript() []session.DisplayEntry
	EarlierHistory() session.EarlierHistory
	RewindPoints() []session.RewindPoint
	RewindAt(index int) ([]session.DisplayEntry, error)
}