# Conflicts: # docs/data/generated/dev-docs.json # internal/app/archied/state_store_test.go # internal/app/archied/state_store_toolcalls_test.go # internal/contracts/state/v1/state.pb.go # internal/daemon/dispatch_bindings_test.go # internal/infrastructure/bindingcipher/cipher_test.go # internal/infrastructure/captureintake/receiver_test.go # internal/infrastructure/edastore/contracts_binding.go # internal/infrastructure/edastore/testsupport_test.go # internal/infrastructure/postgres/edastore.go # internal/infrastructure/postgres/edastore_test.go # internal/infrastructure/staterpc/error_test.go # internal/store/store.go # internal/webui/api_binding_test.go
265 lines
11 KiB
Go
265 lines
11 KiB
Go
// Package events is archied's in-process observability stream. It uses one
|
|
// event type, mutex fan-out, and bounded per-subscriber buffers that DROP on
|
|
// overflow, so a stalled dashboard connection can never apply backpressure to
|
|
// the task engine.
|
|
package events
|
|
|
|
import (
|
|
"sync"
|
|
"sync/atomic"
|
|
"time"
|
|
)
|
|
|
|
// Kind values. Data carries kind-specific fields.
|
|
const (
|
|
KindTaskQueued = "task_queued"
|
|
KindStageStart = "stage_start"
|
|
KindStageFinish = "stage_finish" // data: duration_ms, error
|
|
// KindAgentFinish carries the stage's token economics as well as its
|
|
// outcome: tokens is the run total (agentexec.Result.TokensUsed) and the
|
|
// prompt/completion/cached/cache_creation breakdown is the provider's own
|
|
// accounting, forwarded verbatim for evaluation. The breakdown is absent
|
|
// on events persisted before it was carried across the agent boundary, so
|
|
// consumers must treat each field as optional rather than zero.
|
|
KindAgentFinish = "agent_finish" // data: status, stop_reason, tokens, iterations, model, prompt_tokens, completion_tokens, cached_tokens, cache_creation_tokens
|
|
// KindToolCall marks one completed tool invocation during an agent
|
|
// stage run (archie-core-467's task-transcript counterpart -- the
|
|
// interactive chat gateway surfaces its own tool calls separately via
|
|
// gateway.ToolCallEvent). Only emitted for runners that execute in the
|
|
// same process as their tools; see agentexec.ToolCallReporter.
|
|
KindToolCall = "tool_call" // data: tool, failed
|
|
KindParked = "parked" // data: reason
|
|
KindOutcome = "outcome" // data: status, detail
|
|
KindPRMerged = "pr_merged"
|
|
KindPRRejected = "pr_rejected"
|
|
KindTaskDead = "task_dead"
|
|
// Operator actions taken from the dashboard. Without these an
|
|
// intervention is recorded in the tasks table but invisible on the
|
|
// timeline and the activity stream -- the one kind of event most worth
|
|
// seeing, because it explains why a task changed course.
|
|
KindHumanApproved = "human_approved"
|
|
KindHumanRejected = "human_rejected"
|
|
// KindAgentApproved and KindAgentRejected record that an agent performed
|
|
// the action. They exist because the event kind describes the ACTOR: an
|
|
// agent approving under a person's standing authority is not a human
|
|
// approval, and recording it as one asserts something false. The authority
|
|
// it acted under is PrincipalID, which is a separate fact.
|
|
KindAgentApproved = "agent_approved"
|
|
KindAgentRejected = "agent_rejected"
|
|
// KindTaskApproved and KindTaskRejected record an approval or rejection that
|
|
// archie cannot attribute to anyone: the request carried no identity archie
|
|
// could verify. They are task-level events that claim nothing about the
|
|
// actor, which is the honest record -- a human's approval and an agent's are
|
|
// recorded as human_* and agent_* respectively.
|
|
KindTaskApproved = "task_approved"
|
|
KindTaskRejected = "task_rejected"
|
|
// KindTaskRetried records what the retry was escaping from. RetryTask
|
|
// clears stage and park_reason in the same statement that increments the
|
|
// count, so this event is the only place that context survives.
|
|
KindTaskRetried = "task_retried" // data: retry_count, previous_stage, previous_reason
|
|
KindTaskCancelled = "task_cancelled"
|
|
KindTaskStopped = "task_stopped"
|
|
KindTaskAbandoned = "task_abandoned"
|
|
KindTaskArchiveRequested = "task_archive_requested"
|
|
KindWorkRequestSubmitted = "work_request_submitted"
|
|
KindLog = "log" // data: level, msg
|
|
|
|
// KindChangesCaptured records the change one attempt produced, read off
|
|
// the worktree at the moment it was committed or pushed, plus a final
|
|
// capture once OpenPR knows the number. It is durable
|
|
// provenance, not a live view: the worktree is deleted on merge, close
|
|
// and no-PR terminal states, and a retry resets the branch onto its base,
|
|
// so nothing can re-derive this after the fact. data: schema
|
|
// (ChangesCapturedSchema), owner, repo, base, branch, head_sha, base_sha,
|
|
// pr_number, captured_after, files[], totals, truncated.
|
|
KindChangesCaptured = "changes_captured"
|
|
|
|
// KindConfigCaptured records the effective configuration one attempt ran
|
|
// under, captured where it is materialised for the dispatch. It is durable
|
|
// by requirement, not convenience: the published configuration snapshot is
|
|
// the CURRENT configuration and is replaced on every publish, so it cannot
|
|
// answer what a run that finished last week was configured with. This is
|
|
// the only record of that. data: schema (ConfigCapturedSchema) and document
|
|
// (the JSON encoding of the dispatch's config.TaskConfig, non-secret by
|
|
// construction and by test).
|
|
KindConfigCaptured = "config_captured"
|
|
|
|
// Curator family activity (epic archie-core-yp9). Curator runs ride
|
|
// the same bus so background agents mutating memory stay observable:
|
|
// what ran, when, what changed, and why (archie-core-114).
|
|
KindCuratorRun = "curator_run" // data: curator, actions, at
|
|
KindCuratorAction = "curator_action" // data: curator, type, detail, reason
|
|
KindCuratorError = "curator_error" // data: curator, phase, err
|
|
|
|
// Scheduled-job activity from the ticker engine
|
|
// (internal/domain/scheduling). A scheduled run has no task and no chat
|
|
// turn behind it, so without these a job that fired, stalled or failed
|
|
// is invisible everywhere. data: job, pool, duration_ms (run) and job,
|
|
// pool, phase, err (error).
|
|
KindJobRun = "job_run"
|
|
KindJobError = "job_error"
|
|
|
|
// KindTurnCompleted marks one completed primary chat turn
|
|
// (archie-core-035). Input-driven curators wake on it. Curator output
|
|
// never produces this kind, so derived work cannot feed its own
|
|
// trigger. data: session, channel.
|
|
KindTurnCompleted = "turn_completed"
|
|
|
|
// EDA edit activity (bindings and mappings on the captures store). Each
|
|
// successful write on the State Store's binding and mapping tables emits one
|
|
// event through the same task-DB path capture arrival uses, so a
|
|
// dashboard edit is visible on the activity stream without a manual
|
|
// refresh. data: id (the edited record), action (create, update,
|
|
// approve, delete).
|
|
KindBindingChanged = "binding_changed"
|
|
KindMappingChanged = "mapping_changed"
|
|
|
|
// KindUnsignedEvent marks a task started by an event from an approved
|
|
// unsigned source, so its timeline shows that nothing authenticated
|
|
// the sender. data: source, capture_id, binding_id.
|
|
KindUnsignedEvent = "unsigned_event"
|
|
|
|
// KindUpdateReport carries the phase-2 outcome of a dashboard-initiated
|
|
// update -- whether the restarted daemon came back up healthy and on
|
|
// the version it claimed, relayed once on the boot that finds the
|
|
// pending report left by the update watchdog (archie-core-nln7).
|
|
// data: health_check, rolled_back, confirmed, drift, unverified.
|
|
KindUpdateReport = "update_report"
|
|
)
|
|
|
|
// ConfigCapturedSchema is the schema name carried inside a config_captured
|
|
// event's data. It is named on the wire so a reader can refuse a document it
|
|
// does not understand rather than rendering it as though it did.
|
|
const ConfigCapturedSchema = "archie/task-config@1"
|
|
|
|
// ChangesCapturedSchema is the schema name carried inside a changes_captured
|
|
// event's data, for the same reason as ConfigCapturedSchema: a capture read by
|
|
// a build that does not know its shape is a read failure, and the dashboard has
|
|
// a state for that distinct from a capture it rendered as zeroes.
|
|
const ChangesCapturedSchema = "archie/task-changes@1"
|
|
|
|
// Event is the single wire type: task lifecycle, stage progress, agent
|
|
// stats, and log lines all flow through it -- every consumer (SQLite
|
|
// sink, SSE fan-out, future aggregators) is just another subscriber.
|
|
type Event struct {
|
|
ID int64 `json:"id,omitempty"` // set by the store sink
|
|
At time.Time `json:"at"`
|
|
Kind string `json:"kind"`
|
|
TaskID int64 `json:"task_id,omitempty"`
|
|
Repo string `json:"repo,omitempty"`
|
|
Issue int `json:"issue,omitempty"`
|
|
Workflow string `json:"workflow,omitempty"`
|
|
Stage string `json:"stage,omitempty"`
|
|
// Attempt attributes the event to one run of the task. Zero means
|
|
// UNATTRIBUTED, not "attempt zero": every row written before this field
|
|
// existed, and the deliberately task-agnostic producers, carry 0. A
|
|
// reader must report those as unattributable rather than presenting them
|
|
// as a first run. The tag is deliberately not omitempty so that
|
|
// unattributed and absent stay distinguishable on the wire and in the
|
|
// array the dashboard renders.
|
|
Attempt int `json:"attempt"`
|
|
// ActorID is the identity that performed the action this event records,
|
|
// derived from the credential the request presented. Empty means the event
|
|
// has no actor: the producers that are task-agnostic or pre-date this field
|
|
// make no claim about who acted, and a reader must report that rather than
|
|
// assume a human did.
|
|
ActorID string `json:"actor_id,omitempty"`
|
|
// ActorKind is the acting identity's kind, kept beside ActorID so a reader
|
|
// can tell an agent's action from a person's without resolving the identity
|
|
// -- and so an agent's action can never be displayed as a human's.
|
|
ActorKind string `json:"actor_kind,omitempty"`
|
|
// PrincipalID is the identity whose authority the action used, which is not
|
|
// the acting identity when an agent acts under a person's standing approval
|
|
// ("approved by came from me"). Empty means UNATTRIBUTED: no authority was
|
|
// recorded, which is a different fact from the actor authorising itself.
|
|
PrincipalID string `json:"principal_id,omitempty"`
|
|
Detail string `json:"detail,omitempty"`
|
|
Data map[string]any `json:"data,omitempty"`
|
|
}
|
|
|
|
// Sub is one subscriber: a bounded channel plus a drop counter.
|
|
type Sub struct {
|
|
C <-chan Event
|
|
c chan Event
|
|
dropped atomic.Int64
|
|
bus *Bus
|
|
}
|
|
|
|
// Dropped reports how many events this subscriber missed to overflow.
|
|
func (s *Sub) Dropped() int64 { return s.dropped.Load() }
|
|
|
|
// Close detaches the subscriber and closes its channel.
|
|
func (s *Sub) Close() { s.bus.unsubscribe(s) }
|
|
|
|
// Bus fans events out to subscribers in publish order.
|
|
type Bus struct {
|
|
mu sync.Mutex
|
|
subs []*Sub
|
|
closed bool
|
|
}
|
|
|
|
func NewBus() *Bus { return &Bus{} }
|
|
|
|
// Subscribe registers a subscriber with the given buffer size.
|
|
func (b *Bus) Subscribe(buffer int) *Sub {
|
|
if buffer <= 0 {
|
|
buffer = 64
|
|
}
|
|
s := &Sub{c: make(chan Event, buffer), bus: b}
|
|
s.C = s.c
|
|
b.mu.Lock()
|
|
defer b.mu.Unlock()
|
|
if b.closed {
|
|
close(s.c)
|
|
return s
|
|
}
|
|
b.subs = append(b.subs, s)
|
|
return s
|
|
}
|
|
|
|
// Publish stamps and delivers the event to every subscriber. Full
|
|
// subscriber buffers drop the event (counted) rather than blocking.
|
|
func (b *Bus) Publish(e Event) {
|
|
if e.At.IsZero() {
|
|
e.At = time.Now().UTC()
|
|
}
|
|
b.mu.Lock()
|
|
defer b.mu.Unlock()
|
|
if b.closed {
|
|
return
|
|
}
|
|
for _, s := range b.subs {
|
|
select {
|
|
case s.c <- e:
|
|
default:
|
|
s.dropped.Add(1)
|
|
}
|
|
}
|
|
}
|
|
|
|
func (b *Bus) unsubscribe(sub *Sub) {
|
|
b.mu.Lock()
|
|
defer b.mu.Unlock()
|
|
for i, s := range b.subs {
|
|
if s == sub {
|
|
b.subs = append(b.subs[:i], b.subs[i+1:]...)
|
|
close(s.c)
|
|
return
|
|
}
|
|
}
|
|
}
|
|
|
|
// Close detaches and closes all subscribers; further publishes no-op.
|
|
func (b *Bus) Close() {
|
|
b.mu.Lock()
|
|
defer b.mu.Unlock()
|
|
if b.closed {
|
|
return
|
|
}
|
|
b.closed = true
|
|
for _, s := range b.subs {
|
|
close(s.c)
|
|
}
|
|
b.subs = nil
|
|
}
|