Documentation
¶
Overview ¶
Package delivery is one batch's deliver-and-confirm transaction (cli#907, C1), shared by the host poller and C2's posting CLI (#908). The server decides everything that needs no screen: recipients, filtering, rendering, batching and timing (S1, hadron-server#2017). This package decides only what the terminal shows: whether to type, and whether the text arrived.
It talks to the server through the Server seam. The GraphQL adapter arrives with S1/S5's schema on server main; nothing here depends on it.
Index ¶
- Constants
- Variables
- func BoundWorker(worktree string) string
- func CheckBatch(b Batch) error
- func CheckWake(w Wake) error
- func ClearKeys(leftover string) string
- func ConsumeRelaunchStamp(worktree, worker, session string, now time.Time, ttl time.Duration) (string, bool)
- func HasRelaunchStamp(worktree string) bool
- func KnownCode(code string) bool
- func LockBinding(worktree string, wait time.Duration) (release func(), err error)
- func RenderWake(reasons []WakeReason) string
- func RenderWakeWith(reasons []WakeReason, tickText string) string
- func StopOutboxDir(stateDir string) string
- func ValidCheckpointURN(s string) bool
- func WithWorkerLock(dir, workerID string, fn func(stillOwner func() bool) error) error
- type AckResult
- type Batch
- type Binding
- type Capabilities
- type ChatMessage
- type Cover
- type Deliverer
- type DuplicatePostError
- type Event
- type Kind
- type LaunchBindingIdentity
- type Outcome
- type PendingObservation
- type PendingReport
- type Range
- type Recipient
- type Record
- type Records
- func (s *Records) Delete(workerID string, ranges []Range) error
- func (s *Records) List(workerID string) ([]Record, error)
- func (s *Records) Prune(workerID string, cutoff time.Time) error
- func (s *Records) Put(b Batch, at time.Time) error
- func (s *Records) Retire(workerID string, rec Record, acked []Range) error
- type Registered
- type RelaunchStamp
- type ReportOutcome
- type ReportRun
- type ReporterAPI
- type Server
- type SharedList
- func (s *SharedList) List(ctx context.Context) ([]orcaterm.Terminal, error)
- func (s *SharedList) ListFresh(ctx context.Context) ([]orcaterm.Terminal, error)
- func (s *SharedList) ListShared(ctx context.Context) (terms []orcaterm.Terminal, shared bool, err error)
- func (s *SharedList) Send(ctx context.Context, handle, text string, o orcaterm.SendOptions) orcaterm.Receipt
- type Status
- type StatusBook
- type StopDrop
- type StopOutbox
- type StopReason
- type StopReporter
- type TaskReason
- type Terminals
- type Through
- type TickAction
- type Wake
- type WakeKind
- type WakeRead
- type WakeReason
- type WakeRecord
- type WakeRecords
- func (s *WakeRecords) Acked(workerID string, keys []string, at time.Time) error
- func (s *WakeRecords) List(workerID string) (map[string]WakeRecord, error)
- func (s *WakeRecords) Prune(workerID string, cutoff time.Time) error
- func (s *WakeRecords) Typed(workerID string, reasons []WakeReason, at time.Time) error
- type WakeServer
- type WorkerStatus
Constants ¶
const ( HoldDraft = "draft" HoldIsolated = "isolated" HoldQuestion = "question" HoldScreenUnknown = "screen-unknown" HoldNotSubmitted = "not-submitted" HoldTwoAgents = "two-agents" HoldBindingMismatch = "binding-mismatch" // A plain-directory worker's terminal record (cli#1989): the handle its // own terminal wrote to <dir>/.hadron-team/terminal.json, and the three // checks that stand between that file and typed input. HoldNoTerminalRecord = "no-terminal-record" // the file is missing or unreadable HoldTerminalStale = "terminal-stale" // check (a): not connected, writable and an agent HoldTerminalClaimed = "terminal-claimed" // check (b): another worker's record names it too HoldTerminalBoundElsewhere = "terminal-bound-elsewhere" // check (c): its worktree is another worker's )
Hold reasons: S5's closed vocabulary (hadron-server#2021).
const ( StepRead = "read" StepReadFailed = "read-failed" StepOffByScope = "off-by-scope" // WakeBudgetExhausted: the wake read answered WAKE_BUDGET_EXHAUSTED. WakeBudgetExhausted = "budget-exhausted" )
How a poller step's batch read went (cli#906): the poller reports one per step, so `team host status` can tell a quiet poller from a stopped one.
const ( TickPrefix = "[hadron tick]" TaskPrefix = "[hadron task]" // StopPrefix opens a stop notice's line (hadron-cli#1629, // cor:agt:090:04). StopPrefix = "[hadron stop]" )
Own prefixes of a typed wake line. With Prefix they are what a deliverer recognizes as its own leftover in a composer.
const ( WakeTyped = "typed" WakeAcked = "acked" )
Wake record states (cli#906 6257108208 §1). The two are kept apart: a typed record is pending evidence and never expires by age; only its own landed ack, or a newer tick of the same ticker whose ack landed, moves it to acked. Acked records are archive, pruned after a day.
const AckTimeout = 30 * time.Second
AckTimeout bounds one acknowledgement or hold report, which is sent even while stopping.
const AgentPIDEnv = "HADRON_AGENT_PID"
AgentPIDEnv names the agent's own pid in its environment: an Orca launch exports the launching shell's $$, which the exec keeps, so it is the pid the launcher pinned. `team session reset-context` ends exactly that process, and only when it is the command's own ancestor.
const DefaultBudget = 2*orcaterm.CallTimeout + AckTimeout + 30*time.Second
DefaultBudget is the expiry budget: everything after the screen checks must fit inside the proof's remaining life — a send with --wait-submit and a confirm read (one orca call bound each), the record write, and the ack — plus slack. A proof with less left is re-read, not typed on. This narrows the stale-proof window; it does not close it (network delay, a slow server), and a stale ack after a confirmed send is reconciled from the record, never re-typed.
const DefaultReconcileAfter = 3 * time.Minute
DefaultReconcileAfter is how old an intent must be before it is reconciled and possibly re-sent: well past the CLI's 30 s request timeout.
const DefaultRetainReported = 30 * 24 * time.Hour
DefaultRetainReported is how long a reported record is kept (#1660). A reported notice's record has done its job. The only producer is the poller's flagDroppedHalts, which records a notice each time the server hands the same still-unacknowledged HALT over; if one outlives the window it is recorded and reported once more, which is true (it has still not been typed).
const ( // is busy or unproven and it gave no busy deadline. HoldTimingUnavailable = "timing-unavailable" )
Hold reasons local to a wake. A wake hold is logged and shown in status, never reported to S5 (S5's hold is a batch event).
const MaxTextRunes = 65_536 + 4_096
MaxTextRunes bounds a batch's text by S1's own rule (renderBatch.ts at server main ad7f1c2): at most 10 messages within a 6,000-character body budget, except that the first message is always delivered whole and alone, up to the 65,536-character chat body. The header, authors, parent context, overflow lines and reply hint come on top; 4,096 covers them. A longer text is a contract error. The server counts UTF-16 units, which are never fewer than runes. (Colette's LOCAL P2 on #939: the old 8,000 refused a valid whole message.)
const MaxWakeRunes = 1000
MaxWakeRunes bounds a wake line. A longer one is cut at a reason boundary and says how many reasons it left out.
const Prefix = "[hadron chat"
Prefix opens every rendered batch (D8). It is how a deliverer recognizes its own leftover in a composer: anything else there is someone's draft.
const RecordConfirmed = "confirmed"
RecordConfirmed is the only state a record is ever written in. Nothing is persisted before the delivery test succeeds: a batch read, prepared or sent without confirmation has no record, and counts as not delivered.
const RelaunchStampFile = "hadron-team-relaunch.json"
RelaunchStampFile is what `team session reset-context` leaves beside the session binding (cli#2161, C12): the agent asked for an immediate relaunch of this session after it ends. It is worker-written, so it proves nothing alone: the poller takes it as half of an exit proof, the other half being the exit of the agent it launched, and C5's Runner still applies every guard and the cap. A stamp can only make a relaunch C5 would make happen sooner.
const ScreenMemoLife = 2 * time.Minute
ScreenMemoLife bounds a remembered screen: a stamp is milliseconds and Orca does not promise it moves on every composer edit, so a held line is read again at least this often however quiet the terminal looks (#2181).
const StopDropUnrecorded = "stop-drop-unrecorded"
StopDropUnrecorded is StopDropped when the outbox record could not be written: logged on every poll until it can be.
const StopDropped = "stop-dropped"
StopDropped is the event reason logged, once per notice, when a halt's notice cannot be typed (hadron-cli#1629; Holger's option A on hadron-server#2169: logged and flagged to the coordinator, never typed over a draft, never acknowledged).
Variables ¶
var ErrBindingLockBusy = errors.New("the worktree's session binding is being written")
ErrBindingLockBusy: the binding's writer held the lock for the whole wait.
var ErrBusy = errors.New("another deliverer holds this worker's lock")
ErrBusy is a lock another live deliverer holds. A deliverer that finds it skips the worker this time and never waits: a post must not stall behind the poller.
ErrHoldUnavailable is Hold's answer when the server has no hold report (S5 not on it yet: cli#940). The adapter returns it without a call. The hold stays local: Held and unreported, never Failed, and never cached as reported, so it is reported once the capability is there.
var ErrMalformed = errors.New("malformed batch")
ErrMalformed is a batch that breaks S1's contract. It is neither typed nor acknowledged nor held (S5 has no reason for it, by design): it is logged by span and left due.
var ErrMalformedWake = errors.New("malformed wake")
ErrMalformedWake is a wake that breaks dueWakes' contract: neither typed nor acknowledged, logged by span and left due.
var ErrNoReporterBinding = errors.New("no live reporter binding")
ErrNoReporterBinding: there is no live session bound to the reporter worker, so nothing may be posted. Records stay pending.
var OwnPrefixes = []string{Prefix, TickPrefix, TaskPrefix, StopPrefix}
OwnPrefixes are every prefix C1 types: a leftover opening with any of them is ours (submitted or cleared), never a foreign draft.
Functions ¶
func BoundWorker ¶
BoundWorker is the worker id a worktree's session binding names, "" when it has none (the file does not exist), or unusableBinding when it has one that cannot be trusted.
func CheckBatch ¶
CheckBatch is the shape a batch must have before anything is typed: one line (a newline would submit early), our prefix, a bounded length, and ranges whose seqs lie inside them.
func CheckWake ¶
CheckWake is the shape a wake must have before anything is typed: a proof, a worker, and reasons whose keys are complete.
func ClearKeys ¶
ClearKeys empties a composer holding leftover: one Backspace per rune. It does nothing to an empty composer, so a human who empties it between our read and our send loses nothing. Never Ctrl+C: ONE on an empty Codex composer quits Codex. Never Ctrl+U (one line only) or Esc Esc (Claude opens its Rewind dialog on an empty composer).
func ConsumeRelaunchStamp ¶ added in v0.47.0
func ConsumeRelaunchStamp(worktree, worker, session string, now time.Time, ttl time.Duration) (string, bool)
ConsumeRelaunchStamp reads the stamp once and removes it, then reports whether it named exactly this worker and session within ttl of now, with the checkpoint it names (a valid checkpoints: URN, or "" when false). The caller holds the binding lock. A stamp that was read is gone either way, so it can never match a later exit: one stamp, at most one relaunch.
func HasRelaunchStamp ¶ added in v0.47.0
HasRelaunchStamp says whether a readable stamp sits beside the binding. It reads and consumes nothing: the poller asks it before any network call, so an ordinary exit costs nothing.
func LockBinding ¶ added in v0.45.0
LockBinding takes the worktree's session-binding lock, waiting at most wait for a writer to finish. The caller holds it from its final binding read through its action: Unix releases after each signal syscall, before grace waits; Windows holds through synchronous taskkill and its cancellation/drain. A binding writer waits until this authority is released. The kernel drops the lock when the descriptor closes, including on process death.
A path that is not a worktree or a plain directory at all has no binding location and nothing to lock: the release is a no-op and the error nil. On Unix, a missing plain-directory cache or a missing lock in either binding location is created only as the worktree owner's uid. Existing locks are opened under normal OS permissions. An unreadable .git pointer is an error: nothing can be said about who writes there.
func RenderWake ¶
func RenderWake(reasons []WakeReason) string
RenderWake is the one line typed for reasons (TICK and TASK only). Server-free and count-free, so it holds for a tick with no channels and for every-tick: reasons joined by "; ", cut at a reason boundary to MaxWakeRunes with the count of reasons left out.
func RenderWakeWith ¶ added in v0.32.0
func RenderWakeWith(reasons []WakeReason, tickText string) string
RenderWakeWith is RenderWake for a wake that carries the server's tick text (DueWake.tickText). When reasons hold a TICK and the text is not empty, the text is typed once, whole and first, after TickPrefix, and the TICK reasons' own generic line is dropped; TASK parts follow. The tick text is never reworded, joined, repaired or cut (cor:agt:080:26): MaxWakeRunes bounds the TASK parts only, so a long tick text leaves fewer of them, or none, and a text longer than the bound is typed whole. A text the host cannot type as one line (a control character, a line break or an escape) is dropped whole, never repaired (R4): the wake then types what it would without tick text, so a tick-only wake still names its ticker. With no tick text, or no TICK reason, this is RenderWake.
func StopOutboxDir ¶ added in v0.37.0
StopOutboxDir is the outbox under a host's delivery state directory: the one place the poller (New) and the reporter (report-stops) both take it.
func ValidCheckpointURN ¶ added in v0.47.0
ValidCheckpointURN says whether s is a checkpoint URN a stamp may carry.
func WithWorkerLock ¶
WithWorkerLock runs fn holding workerID's lock under dir. fn receives stillOwner, re-checked before every send and every write, so a deliverer that somehow lost the lock stops instead of acting alongside another.
Types ¶
type Batch ¶
type Batch struct {
// ID is S1's signed proof. It is sent back to ack or hold and nowhere
// else: never logged, stored or put in argv.
ID string
// BatchKey is S1's stable hash over the ranges: the same messages, the
// same key, across re-issued proofs. A lookup key, never evidence.
BatchKey string
WorkerID string
Ranges []Range
Text string
// DeliverAfter has passed for every batch S1 returns; it is checked
// anyway. BusyDeadline is DeliverAfter plus S9's busy-delay cap: a
// working agent defers a batch until then and no later.
DeliverAfter time.Time
BusyDeadline time.Time
ProofExpiresAt time.Time
// Interrupt is set only for a halt (S6, phase 4): always false now.
Interrupt bool
}
Batch is one ready-to-deliver batch as S1 renders it.
type Binding ¶ added in v0.45.0
type Binding struct {
// WorkerID is "" when the worktree has no binding file.
WorkerID string
// SessionID is "" when there is no binding or it names no session.
SessionID string
// Unusable is a binding file that exists but cannot be trusted
// (unreadable, not JSON, naming no worker): never the same as none.
Unusable bool
}
Binding is what a worktree's session binding names (hadron-cli#2057).
func WorktreeBinding ¶ added in v0.45.0
WorktreeBinding reads the worker and session a worktree's session binding names, by the same rules as BoundWorker.
type Capabilities ¶
type Capabilities struct {
// EnterOnly: an Enter-only send submits what the composer holds.
EnterOnly map[string]bool
// Clear: ClearKeys empties the family's composer.
Clear map[string]bool
}
Capabilities are what has been PROVEN on a scratch terminal, per TUI family. Until proven, the path it would enable holds instead.
func Proven ¶
func Proven() Capabilities
Proven is what the 2026-10-18 scratch terminal proved on Claude Code 2.1.303 and Codex CLI 0.163.0 (cli#907; hadron-dev-team-joshua:work: cli907-scratch-terminal-evidence-2026-10-18): Enter alone submits an existing composer, and ClearKeys empties one, multi-line included.
type ChatMessage ¶ added in v0.37.0
ChatMessage is the part of a team-chat message the reporter compares.
type Cover ¶
type Cover struct {
// Full: every message of the batch was confirmed delivered. Ack it whole,
// with no typing.
Full bool
// Through: the channels with a confirmed covered prefix, when not Full.
// Channels left out are not covered and move nothing.
Through []Through
// Matched are the records that proved it.
Matched []Record
}
Cover is what confirmed records prove about a batch.
func Reconcile ¶
Reconcile is what confirmed records prove about b. A record applies to a channel only when the channel id AND the incarnation match: a recreated channel restarts its seqs on the same id (hadron-server src/lib/channels.ts at b8384631), so an earlier incarnation's record proves nothing. Within a channel the covered prefix is the batch's own seqs from its first, for as long as each is in one record's confirmed seqs. The first seq not in the record ends it, so a later distinct message is never acked unseen, and a batch whose first seq the record lacks gets no ack at all. (cli#907 delta 2 also asked that the record START at the batch's first seq. That only ever refused a record starting earlier, e.g. [4,5,6] against [5,6,7], which proves 5 and 6 confirmed: refusing it would retype them.) A batchKey match with a confirmed record is a full cover by S1's definition of the key.
type Deliverer ¶
type Deliverer struct {
Server Server
Orca Terminals
Records *Records
// LockDir holds the per-worker locks shared with C2.
LockDir string
Caps Capabilities
// Bound is the worker a worktree's session binding names, or "".
Bound func(worktree string) string
// Registered lists every registered worker's directories, for the
// plain-directory claim checks (cli#1989). nil: only the recipient.
Registered func() Registered
// ProcessGone says no process has a pid (ESRCH and nothing else); nil is
// the host's real test. A seam for the claim liveness tests.
ProcessGone func(pid int) bool
Now func() time.Time
Budget time.Duration
Emit func(Event)
// Wakes acknowledges wake proofs; nil leaves wakes unacknowledged.
Wakes WakeServer
WakeRecords *WakeRecords
// AckMixed is set only once A′ (hadron-server#2072) is verified
// deployed: a wake carrying a MENTION, or naming channels, may then be
// acknowledged once all its TICK and TASK reasons are typed. Off, C1
// acknowledges only a proof with no MENTION reason and no channels.
AckMixed bool
// StopDrops is the dropped-halt outbox (hadron-cli#1629). nil records
// nothing, and a drop is then logged as unrecorded.
StopDrops *StopOutbox
// contains filtered or unexported fields
}
Deliverer delivers batches into Orca terminals.
func (*Deliverer) Deliver ¶
Deliver carries one batch to its recipient's terminal, under the worker's lock. The order is the design (cli#907 attach §2 and deltas 2–4): reconcile confirmed records first (never type what was confirmed), check the batch and the proof's remaining life, find exactly one agent terminal in a registered worktree with a matching binding, judge its composer under R2 and its liveness, then send, confirm, record, and ack.
func (*Deliverer) DeliverWake ¶
DeliverWake types w's not-yet-recorded TICK and TASK reasons into r's terminal as one line, records them, and acknowledges the proof when the accepted set allows it.
The order mirrors a batch's: reconcile records first (a reason already typed is never typed again), then the shared terminal path, then record every typed key before the ack. A proof is acknowledged only when ackable.
type DuplicatePostError ¶ added in v0.37.0
type DuplicatePostError struct{ EarlierSeq int }
DuplicatePostError is the server's TEAM_CHAT_DUPLICATE refusal: an identical post by this worker already exists at EarlierSeq.
func (*DuplicatePostError) Error ¶ added in v0.37.0
func (e *DuplicatePostError) Error() string
type Event ¶
type Event struct {
Time time.Time
Worker string
WorkerID string
Span string
Kind Kind
Reason string
Terminal string
// ResolvedBy says where the recipient terminal's agent family came
// from: "identity" (Orca's agent identity) or "screen" (Orca reported
// none, and the screen showed one). Empty before a terminal is found. A
// diagnostic code only (cli#906): it grants nothing.
ResolvedBy string
// Wake: the event is a tick or task wake's (cli#906 row 1), not a
// batch's. Span is then reason counts.
Wake bool
// Unreported: a hold the server was not told about (cli#940).
Unreported bool
}
Event is one line of what delivery did, for the operator.
type Kind ¶
type Kind string
Kind is a delivery's outcome.
const ( Delivered Kind = "delivered" // typed and confirmed Reconciled Kind = "reconciled" // acknowledged from a confirmed record, nothing typed Held Kind = "held" // left due with a reason; reported to S5 unless Unreported (#940) Deferred Kind = "deferred" // left due: try again next time Skipped Kind = "skipped" // left due, without a hold (no terminal, lock busy) Failed Kind = "error" // a contract or transport error; left due )
type LaunchBindingIdentity ¶ added in v0.46.0
type LaunchBindingIdentity struct {
WorkerID string `json:"workerId"`
SessionID string `json:"sessionId"`
AppID string `json:"appId"`
Server string `json:"server"`
Usable bool `json:"-"`
}
LaunchBindingIdentity is a complete local binding, required for relaunch. Older incomplete bindings remain usable by legacy readers but prove nothing for a new process launch. Reading it never refreshes or rewrites a session.
func WorktreeBindingIdentity ¶ added in v0.46.0
func WorktreeBindingIdentity(worktree string) LaunchBindingIdentity
type Outcome ¶
type Outcome struct {
Kind Kind
Reason string
Terminal string
// AckPending: delivered and recorded, but the ack did not land; the
// record reconciles it next time without typing.
AckPending bool
// Unreported: Held, but the server was not told (ErrHoldUnavailable).
// No server hold, episode, alarm or escalation exists for it.
Unreported bool
}
Outcome is what one Deliver did. Reason is a code; nothing here carries text, a proof or screen content.
type PendingObservation ¶ added in v0.40.0
type PendingReport ¶ added in v0.40.0
type PendingReport struct {
Pending int `json:"pending"`
Stale int `json:"stale"`
NeedsPerson int `json:"needsPerson"`
// Corrupt counts record files that could not be read; they are not in
// Pending (no notice can be read from them) and a run reports them failed.
Corrupt int `json:"corrupt,omitempty"`
Records []PendingObservation `json:"records"`
RecordsTotal int `json:"recordsTotal"`
RecordsTruncated bool `json:"recordsTruncated"`
}
PendingReport is a cached observation, never a current diagnosis or authority.
type Range ¶
type Range struct {
ChannelID string `json:"channelId"`
Incarnation int `json:"incarnation"`
FromSeq int `json:"fromSeq"`
ThroughSeq int `json:"throughSeq"`
Seqs []int `json:"seqs"`
}
Range is one channel's part of a batch (S1 #2017 issuecomment-6246620593). Seqs are the exact message seqs rendered, at most ten across the batch.
type Recipient ¶
type Recipient struct {
WorkerID string
Name string
// TUI is the agent interface its terminal must show ("claude" or
// "codex"), when the host knows it. Empty means the screen's own family
// and Orca's agent identity must agree instead.
TUI string
// Worktrees are its registered worktrees, absolute.
Worktrees []string
// contains filtered or unexported fields
}
Recipient is a worker registered on this host, as the poller's latest registration resolved it.
type Record ¶
type Record struct {
State string `json:"state"`
WorkerID string `json:"workerId"`
BatchKey string `json:"batchKey,omitempty"`
Ranges []Range `json:"ranges"`
ConfirmedAt time.Time `json:"confirmedAt"`
}
Record is submitted evidence for one batch: written after a confirmed send and before its ack, deleted once the ack lands. It holds no text, no proof and no batch id.
type Records ¶
type Records struct {
Dir string
}
Records is the confirmed-delivery store: one 0600 file per batch under a 0700 directory per worker. Files are written by atomic rename and named by a hash of the ranges, so a writer that lost its lock never clobbers another deliverer's record.
func (*Records) List ¶
List is the worker's confirmed records. A file that does not parse as a confirmed record for this worker is ignored: only typed, confirmed evidence may suppress a send.
func (*Records) Prune ¶
Prune drops records confirmed before cutoff: past the proof's lifetime a record can only match a re-hand, and S1 re-hands within minutes.
func (*Records) Retire ¶
Retire removes from rec the messages an ack just covered (acked, the acknowledged batch's ranges) and keeps the rest: a record can confirm seqs or channels the acknowledged batch did not carry, and those are still owed their own ack (Jane's P2 on #939). The remainder keeps rec's confirmation time and drops its batchKey, which named the whole. It is written before rec is removed, so a crash between leaves both, which only proves the same messages twice. A record with nothing left is deleted.
type Registered ¶ added in v0.45.0
Registered maps each worker registered on this host (Recipient.Name) to its registered directories, absolute. It is how the claim checks learn the OTHER workers' claims; a nil Registered knows only the recipient.
type RelaunchStamp ¶ added in v0.47.0
type RelaunchStamp struct {
Version int `json:"version"`
WorkerID string `json:"workerId"`
SessionID string `json:"sessionId"`
Checkpoint string `json:"checkpoint"`
RequestedAt time.Time `json:"requestedAt"`
}
RelaunchStamp is the stamp's whole shape (version 1).
type ReportOutcome ¶ added in v0.37.0
type ReportOutcome struct {
EventID string `json:"eventId"`
Worker string `json:"worker"`
// Result: reported, reconciled, duplicate, waiting, failed.
Result string `json:"result"`
Seq int `json:"seq,omitempty"`
// File names an outbox record that could not be read (#1660); such an
// outcome has no event id or worker, and is always failed.
File string `json:"file,omitempty"`
Error string `json:"error,omitempty"`
Reason string `json:"reason,omitempty"`
Field string `json:"field,omitempty"`
DiagnosticError string `json:"diagnosticError,omitempty"`
}
ReportOutcome is one record's result in a run.
type ReportRun ¶ added in v0.37.0
type ReportRun struct {
// Busy: another reporter holds the lock; this run did nothing.
Busy bool `json:"busy"`
Outcomes []ReportOutcome `json:"outcomes"`
// Pruned counts reported records removed by the retention rule this run.
Pruned int `json:"pruned,omitempty"`
}
ReportRun is a whole run's result.
type ReporterAPI ¶ added in v0.37.0
type ReporterAPI interface {
// BoundWorker answers the worker of the LIVE session bound for this
// reporter. It errors when there is no binding or the session ended.
BoundWorker(ctx context.Context) (workerID, workerName string, err error)
// Recipient is the mention token (no "@") of whom to flag for a halted
// worker: its reportsTo worker, else the person holding it.
Recipient(ctx context.Context, workerID string) (string, error)
// Head is the channel's newest seq (0 when empty).
Head(ctx context.Context) (int, error)
// Post posts body as the bound worker and answers its seq. A duplicate
// refusal is a *DuplicatePostError.
Post(ctx context.Context, body string) (int, error)
// MessagesAfter answers messages with seq > after, ascending, at most
// limit; an empty page means none remain.
MessagesAfter(ctx context.Context, after, limit int) ([]ChatMessage, error)
}
ReporterAPI is what the reporter needs from the server. The CLI implements it over the worktree's worker-session binding; tests fake it.
type Server ¶
type Server interface {
Ack(ctx context.Context, batchID string, through []Through) (AckResult, error)
Hold(ctx context.Context, batchID, reason, terminalID string) error
}
Server is S1's acknowledgement and S5's hold, as delivery consumes them. An Ack error of any kind (a refusal included: BAD_USER_INPUT, WAKE_PROOF_STALE) means nothing moved, so a confirmed record is kept.
type SharedList ¶ added in v0.47.1
type SharedList struct {
// contains filtered or unexported fields
}
SharedList is a Terminals whose List is shared by every delivery within a short window, so a poll cycle's cost is one `orca terminal list` however many workers it decides for (#2181). The list only finds a worker's terminal; the composer, the question, the idle proof and the binding are all judged from a screen read afterwards, so a list a few seconds old cannot make a send safe that is not.
Never shared: a failed list (the next caller asks again), and any list older than the window or older than a Send (a send changes a terminal, so the next delivery looks fresh).
func NewSharedList ¶ added in v0.47.1
NewSharedList wraps inner so one List answers every caller within ttl.
func (*SharedList) List ¶ added in v0.47.1
List is the shared list: the one call a window needs, made under the lock so concurrent deliveries wait for it instead of each making their own.
func (*SharedList) ListFresh ¶ added in v0.47.1
ListFresh is a list made now, whatever the window holds, and the new shared list. A delivery that is about to type or clear a composer asks for this: a second agent terminal, a moved worktree or a closed tab that appeared inside the window must still refuse the send.
func (*SharedList) ListShared ¶ added in v0.47.1
func (s *SharedList) ListShared(ctx context.Context) (terms []orcaterm.Terminal, shared bool, err error)
ListShared is List that also says whether the answer came from the window (a list another delivery made). A delivery that would type judges such a list stale: see ListFresh.
func (*SharedList) Send ¶ added in v0.47.1
func (s *SharedList) Send(ctx context.Context, handle, text string, o orcaterm.SendOptions) orcaterm.Receipt
Send types through inner and ends the shared list: what follows looks fresh.
type Status ¶
type Status struct {
Version int `json:"version"`
LastStepAt time.Time `json:"lastStepAt"`
LastRead string `json:"lastRead"`
Workers map[string]WorkerStatus `json:"workers"`
// The newest wake read (cli#906 row 1): its code, and dueWakes' counts.
WakeRead string `json:"wakeRead,omitempty"`
BudgetExhaustedAt *time.Time `json:"budgetExhaustedAt,omitempty"`
Dormant int `json:"dormant"`
Withheld int `json:"withheld"`
}
Status is the poller's local delivery snapshot. It is observational: what this host's poller last saw, never authoritative delivery health (that is S5's). It holds no text, proof, draft or batch id.
func ReadStatus ¶
ReadStatus reads the snapshot under stateDir. A missing file is an fs.ErrNotExist error; a corrupt one is any other error.
type StatusBook ¶
type StatusBook struct {
// contains filtered or unexported fields
}
StatusBook keeps the snapshot as events arrive and writes it after each poller step. Safe for concurrent use: deliveries for different workers run at once.
func NewStatusBook ¶
func NewStatusBook(stateDir string) *StatusBook
NewStatusBook keeps the snapshot under stateDir, beside the records and locks. It starts from the workers the last snapshot saved, so a worker's run of holds and its newest event survive a poller restart (Jane's LOCAL P2 on #1183). A missing or unreadable snapshot starts empty.
func (*StatusBook) Observe ¶
func (b *StatusBook) Observe(e Event)
Observe records e as its worker's newest event, unless an event already recorded is newer. It writes nothing: Step does.
func (*StatusBook) ObserveWakes ¶
func (b *StatusBook) ObserveWakes(r WakeRead)
ObserveWakes records a step's wake read. It writes nothing: Step does. The budget time is kept only while the newest read says it is spent.
type StopDrop ¶ added in v0.37.0
type StopDrop struct {
EventID string `json:"eventId"`
SignalID string `json:"signalId"`
WorkerID string `json:"workerId"`
Worker string `json:"worker"`
Level string `json:"level"`
HoldReason string `json:"holdReason"`
HeldAt time.Time `json:"heldAt"`
// TypedAt is set once the same notice is later typed and acknowledged,
// so a report can say it has since landed. Zero while it is still due.
TypedAt time.Time `json:"typedAt,omitzero"`
}
StopDrop is the outbox record of a halt notice the poller could not type (hadron-cli#1629; Holger's option A on hadron-server#2169: a dropped interrupt is logged and flagged to the coordinator). Ids and codes only: never screen, draft or proof text. The poller writes it once per notice; the host's reporter reads it, posts the flag, and writes its own <name>.reported marker beside it, which the poller never touches.
type StopOutbox ¶ added in v0.37.0
type StopOutbox struct {
Dir string
}
StopOutbox is the dropped-halt outbox: one 0600 file per notice under a 0700 directory, created at most once (link, which fails if the name exists), so a notice held on every poll, or across a poller restart, is recorded once.
func (*StopOutbox) Drop ¶ added in v0.37.0
func (o *StopOutbox) Drop(rec StopDrop) (created bool, err error)
Drop records rec unless its notice is already recorded. created is true only for the first record of that notice.
func (*StopOutbox) List ¶ added in v0.37.0
func (o *StopOutbox) List() ([]StopDrop, error)
List is every recorded notice, for the reporter and status. Markers and temporaries are skipped; an unreadable record is an error, never skipped.
type StopReason ¶ added in v0.37.0
StopReason is the notice a STOP reason carries (DueStopReason), as the server gave it. Interrupt is carried and never acted on: under Holger's option A no notice sends an interrupt key (hadron-cli#1629).
type StopReporter ¶ added in v0.37.0
type StopReporter struct {
Outbox *StopOutbox
API ReporterAPI
ReporterWorker string
Now func() time.Time
ReconcileAfter time.Duration
// RetainReported is how long after its report a record is kept before a
// run removes it. Zero means DefaultRetainReported; a negative value keeps
// reported records forever. A record with no report marker is never removed.
RetainReported time.Duration
// contains filtered or unexported fields
}
StopReporter flags dropped halts from an outbox.
func (*StopReporter) Pending ¶ added in v0.37.0
func (r *StopReporter) Pending(olderThan time.Duration) (pending, stale int, err error)
Pending reports how many records have no marker (pending) and, of those, how many were first held more than olderThan ago. Read-only; takes no lock.
func (*StopReporter) PendingStatus ¶ added in v0.40.0
func (r *StopReporter) PendingStatus(olderThan time.Duration) (PendingReport, error)
PendingStatus reads only local state, without taking a lock or creating files.
type TaskReason ¶
type TaskReason struct {
EventID string
ChainIndex int
// Event is the line's wording: "assigned", "child finished", "alarm" or
// "end session".
Event string
// ID and Title are the task's. A task-less alarm (S5 #2021
// comment-6259060238: taskId null) has neither, and none is invented.
ID string
Title string
// Handle is the task's AT handle (DueTaskReason.handle, cor:agt:050:01),
// printed first on the TASK line ahead of the short id. Empty falls back
// to the full id and is never invented.
Handle string
// AlarmType is a task-less alarm's closed type code from the server
// (e.g. delivery.stuck), shown as given.
AlarmType string
}
TaskReason is the task a TASK reason is for (DueTaskReason).
type Terminals ¶
type Terminals interface {
List(ctx context.Context) ([]orcaterm.Terminal, error)
ReadScreen(ctx context.Context, handle string) *orcaterm.Screen
Send(ctx context.Context, handle, text string, o orcaterm.SendOptions) orcaterm.Receipt
}
Terminals is the orca surface delivery uses; *orcaterm.Client is one.
type Through ¶
Through limits an ack to a channel's covered prefix: Seq must be one of that channel's rendered seqs (S1), and the mark moves from the range's start to Seq and no further. Channels left out move nothing.
type TickAction ¶ added in v0.32.0
TickAction is WakeReason.action: the server's answer, shown never composed.
type Wake ¶
type Wake struct {
// Proof is the signed proof handed back to acknowledgeWakes. Never
// logged, stored or put in argv.
Proof string
WorkerID string
Reasons []WakeReason
// NamesChannels: the proof carries channel ranges (DueWake.channels is
// non-empty). Before A′ is deployed, acknowledging such a proof could
// mark unseen text delivered, so C1 never does.
NamesChannels bool
// DeliverAfter and BusyDeadline are S1 slice (c)'s timing (R63): the
// busy deadline counts from the oldest waiting reason's due time. A zero
// one means the server did not say, and C1 invents none: no
// DeliverAfter holds the wake as timing-unavailable even for an idle
// agent, and no BusyDeadline holds it so for a busy or unproven one.
DeliverAfter time.Time
BusyDeadline time.Time
// TickText is DueWake.tickText: the one line the server wrote for the
// wake's ticks (cor:agt:080:26). Typed unchanged, never recorded.
TickText string
}
Wake is one due wake as dueWakes returns it.
type WakeRead ¶
WakeRead is how a step's wake read went (cli#906 row 1): its code and the counts dueWakes reports for status. Counts only.
type WakeReason ¶
type WakeReason struct {
Kind WakeKind
TickerID string
TickerName string
// LastTickAt names the tick (k) a TICK reason is for: it changes per
// tick, so with the ticker it is the reason's stable identity.
LastTickAt time.Time
Task *TaskReason
// Action is what the register says this tick asks of the woken worker
// (TICK only). Carried for the dueWakes adapter and status; never
// rendered, never part of Key().
Action *TickAction
// Stop is set for a STOP reason (hadron-cli#1629).
Stop *StopReason
}
WakeReason is one reason a wake is due.
func (WakeReason) Key ¶
func (r WakeReason) Key() string
Key is the reason's stable submitted identity: tick:<tickerId>:<lastTickAt>, task:<eventId>:<chainIndex> or stop:<eventId> (the notice's event, hadron-cli#1629). "" for a MENTION, which C1 never records.
type WakeRecord ¶
type WakeRecord struct {
State string `json:"state"`
WorkerID string `json:"workerId"`
Key string `json:"key"`
TickerID string `json:"tickerId,omitempty"`
TickAt time.Time `json:"tickAt,omitzero"`
At time.Time `json:"at"`
}
WakeRecord is submitted evidence for one TICK or TASK reason. It holds the reason's key and nothing else from the wake: no text, no proof.
type WakeRecords ¶
type WakeRecords struct {
Dir string
}
WakeRecords is the wake-reason store: one 0600 file per key under a 0700 directory per worker, written by atomic rename.
func (*WakeRecords) Acked ¶
Acked moves records to acked. A key with no record is skipped: only typed evidence is ever archived.
func (*WakeRecords) List ¶
func (s *WakeRecords) List(workerID string) (map[string]WakeRecord, error)
List is the worker's wake records, keyed by reason key. A file that does not parse as this worker's record under its own name is ignored.
func (*WakeRecords) Prune ¶
func (s *WakeRecords) Prune(workerID string, cutoff time.Time) error
Prune drops acked records older than cutoff. Typed records are never pruned by age.
func (*WakeRecords) Typed ¶
func (s *WakeRecords) Typed(workerID string, reasons []WakeReason, at time.Time) error
Typed records reasons whose line was confirmed submitted. Written after the confirmation and before any ack.
type WakeServer ¶
WakeServer is acknowledgeWakes, for one proof C1 itself read. An error of any kind means nothing moved.
type WorkerStatus ¶
type WorkerStatus struct {
Name string `json:"name"`
Kind Kind `json:"kind"`
Reason string `json:"reason,omitempty"`
At time.Time `json:"at"`
ResolvedBy string `json:"resolvedBy,omitempty"`
// Wake: the event was a tick or task wake's, not a batch's.
Wake bool `json:"wake,omitempty"`
// Unreported: the newest event was a hold the server was not told about.
Unreported bool `json:"unreported,omitempty"`
// HeldSince is when the worker's current run of holds began: set by its
// first hold, kept through later holds, deferrals, skips and errors, and
// cleared only by a delivered or reconciled event (cli#1178). Nil when
// no hold is outstanding.
HeldSince *time.Time `json:"heldSince,omitempty"`
}
WorkerStatus is a worker's newest delivery event: codes only.
Source Files
¶
- batch.go
- binding.go
- bindinglock.go
- bindinglock_unix.go
- bindingowner_unix.go
- deliver.go
- lock.go
- plaindir.go
- proc_unix.go
- readregular_unix.go
- records.go
- relaunch_binding.go
- relaunch_stamp.go
- relaunch_stamp_unix.go
- reporter_lock_unix.go
- sharedlist.go
- status.go
- stop_lastfail_unix.go
- stop_outbox.go
- stop_reporter.go
- wake.go
- wake_records.go