Documentation
¶
Overview ¶
Package coord implements the coordination layer of dibs: leases on file patterns, agent presence, broadcast notes, and the event journal.
All state is plain JSON files under the store's State dir. Nothing here runs in the background: expiry is evaluated lazily whenever state is read or mutated, so dibs needs no daemon.
Index ¶
- Constants
- func AutoName(worktree string) string
- func Intersect(a, b string) bool
- func Normalize(p, repoRoot string) (string, error)
- type AgentInfo
- type Conflict
- type Event
- type Lease
- type Manager
- func (m *Manager) ActiveLeases() ([]Lease, error)
- func (m *Manager) Agents() ([]AgentInfo, error)
- func (m *Manager) Check(paths []string) ([]Conflict, error)
- func (m *Manager) Claim(patterns []string, reason string, ttl time.Duration) (*Lease, []Conflict, error)
- func (m *Manager) Journal(n int) ([]Event, error)
- func (m *Manager) MarkNotesRead() error
- func (m *Manager) Notes() ([]Note, error)
- func (m *Manager) PostNote(msg string) (*Note, error)
- func (m *Manager) Release(ids, patterns []string, all bool) ([]Lease, error)
- func (m *Manager) Renew(ttl time.Duration) ([]Lease, error)
- func (m *Manager) Touch()
- func (m *Manager) UnreadNotes() ([]Note, error)
- type Note
Constants ¶
const ( DefaultTTL = 30 * time.Minute MaxTTL = 24 * time.Hour )
Variables ¶
This section is empty.
Functions ¶
func AutoName ¶
AutoName derives a stable, human-friendly agent name from a worktree path. The same worktree always maps to the same name, so an agent working in ./wt-auth is "the same agent" across sessions without any configuration.
Types ¶
type AgentInfo ¶
type AgentInfo struct {
Name string `json:"name"`
Worktree string `json:"worktree,omitempty"`
Branch string `json:"branch,omitempty"`
LastReason string `json:"last_reason,omitempty"`
FirstSeen time.Time `json:"first_seen"`
LastSeen time.Time `json:"last_seen"`
LastNoteRead time.Time `json:"last_note_read,omitempty"`
}
AgentInfo is what dibs knows about one agent, updated as a side effect of every command that agent runs. There are no heartbeats: freshness is simply "when did it last do something".
type Conflict ¶
Conflict pairs a requested pattern (or checked path) with the foreign lease that covers it.
type Event ¶
type Event struct {
At string `json:"at"`
Event string `json:"event"`
Agent string `json:"agent"`
Details map[string]any `json:"details,omitempty"`
}
Event is one line of the append-only journal: who did what, when. The journal is the answer to "what have the agents been doing?".
type Lease ¶
type Lease struct {
ID string `json:"id"`
Agent string `json:"agent"`
Patterns []string `json:"patterns"`
Reason string `json:"reason,omitempty"`
CreatedAt time.Time `json:"created_at"`
ExpiresAt time.Time `json:"expires_at"`
Renewals int `json:"renewals,omitempty"`
Worktree string `json:"worktree,omitempty"`
Branch string `json:"branch,omitempty"`
}
Lease is one agent's claim on a set of file patterns for a limited time.
type Manager ¶
Manager performs coordination operations as one named agent.
func NewManager ¶
NewManager resolves the acting agent's identity and returns a manager. Identity precedence: explicit name (--agent) > DIBS_AGENT env > a stable name derived from the worktree path.
func (*Manager) ActiveLeases ¶
ActiveLeases returns unexpired leases without mutating state.
func (*Manager) Check ¶
Check reports which of the given repo-relative paths are covered by another agent's active lease. It never mutates state, so it is safe and fast to call from hooks on every file edit.
func (*Manager) Claim ¶
func (m *Manager) Claim(patterns []string, reason string, ttl time.Duration) (*Lease, []Conflict, error)
Claim asks for a lease on patterns. It returns either the granted (or renewed) lease, or the list of conflicts that denied it.
func (*Manager) MarkNotesRead ¶
MarkNotesRead advances this agent's read cursor to now.
func (*Manager) Release ¶
Release drops leases held by this agent: all of them, by lease ID, or by exact pattern. It returns the leases that were released.
func (*Manager) Touch ¶
func (m *Manager) Touch()
Touch records activity for this agent; exported for commands that don't otherwise mutate state (status, mcp startup).
func (*Manager) UnreadNotes ¶
UnreadNotes returns notes from other agents newer than this agent's read cursor.
type Note ¶
type Note struct {
ID string `json:"id"`
From string `json:"from"`
Message string `json:"message"`
CreatedAt time.Time `json:"created_at"`
}
Note is a small broadcast message between agents: "I changed the User schema — regenerate types before touching api/". Notes are the handoff mechanism; anything bigger belongs in a lesson or a commit message.
Source Files