refactor: cut remaining long comments down to what the code does

This commit is contained in:
sam committed 2026-10-03 22:06:57 +10:00
1 parent 0cbb65c684
commit cb6b8618c2
141 files changed
+610 -2622

No files matched your search

+2 -9
View File
@@ -1,12 +1,5 @@
// Package configtemplate embeds config.example.toml so archied setup can // Package configtemplate embeds config.example.toml for archied setup. It
// generate a first-run config.toml from the exact file operators already // sits at the module root because embed cannot reach parent directories.
// read as documentation, instead of a second copy that can drift from it.
//
// It lives at the module root, rather than under internal/, because embed
// patterns cannot reach outside the directory of the .go file that declares
// them, and config.example.toml is kept at the root where it is easy to
// find and hand-edit. (Written without the directive prefix on purpose:
// staticcheck reads "// go:embed" in prose as a malformed directive.)
package configtemplate package configtemplate
import _ "embed" import _ "embed"
+4 -18
View File
@@ -1,11 +1,5 @@
// Package archieplaybooks is the application composition for the standalone // Package archieplaybooks implements the archie-playbooks CLI, using the
// playbook-validation CLI (cmd/archie-playbooks). It owns the lint mode's // daemon's own playbook loaders.
// orchestration: collect the configured directories, run the domain
// validators, and shape the outcome for human consumption. The rules live in
// internal/domain/workflow (routing binding files) and
// internal/domain/eda/playbook (EDA playbooks) -- this package only calls the
// loaders the daemon runs and formats results; there is deliberately no
// second validation path here.
package archieplaybooks package archieplaybooks
import ( import (
@@ -24,16 +18,8 @@ type Result struct {
Findings []string Findings []string
} }
// Lint validates one or more playbook directories against the domain // Lint validates playbook directories with workflow.LoadPlaybookDirs and
// loaders and reports every collision / malformed file / invalid binding as // reports every finding. It returns 0 when clean, 1 otherwise.
// a finding. It returns exit code 0 on a clean set, 1 when any finding is
// reported. Directories and single-file fields share one validation source:
//
// workflow.LoadPlaybookDirs
//
// which already applies the same rules LoadKindWorkflowsYAML and
// LoadLabelWorkflowsYAML do, per file and across files -- so the linter can
// never disagree with the daemon's startup validation.
func Lint(dirs []string, stderr io.Writer) Result { func Lint(dirs []string, stderr io.Writer) Result {
var findings []string var findings []string
+3 -5
View File
@@ -17,11 +17,9 @@ import (
"gopkg.in/yaml.v3" "gopkg.in/yaml.v3"
) )
// Serve runs the language server over rwc until the client disconnects or // Serve runs the language server over rwc until the client disconnects or ctx
// ctx ends. It publishes diagnostics when a playbook file is opened or saved, // ends, publishing diagnostics for the saved directory when a playbook is
// by linting the file's saved directory with the loader the daemon runs for // opened or saved.
// it: the whole directory, because a collision is a cross-file finding.
// Unsaved edits are not validated.
func Serve(ctx context.Context, rwc io.ReadWriteCloser) error { func Serve(ctx context.Context, rwc io.ReadWriteCloser) error {
s := &server{exited: make(chan struct{})} s := &server{exited: make(chan struct{})}
_, conn, client := protocol.NewServer(ctx, s, jsonrpc2.NewStream(rwc)) _, conn, client := protocol.NewServer(ctx, s, jsonrpc2.NewStream(rwc))
+1 -5
View File
@@ -1,8 +1,4 @@
// Package email implements gateway.Gateway for inbound email via SMTP. // Package email receives email over SMTP and replies through an SMTP relay.
// A lightweight SMTP server receives emails on a configurable port
// (intended for localhost use behind a mail relay like Postfix).
// Inbound messages are routed through the gateway for LLM processing;
// replies are sent via SMTP relay to the original sender.
package email package email
import ( import (
+5 -15
View File
@@ -20,12 +20,8 @@ const defaultEphemeralDeleteTimeout = 30 * time.Second
// of that message is then skipped rather than attempted blindly. // of that message is then skipped rather than attempted blindly.
type SendFunc func(ctx context.Context, event messaging.MessageEvent) (messaging.MessageEvent, error) type SendFunc func(ctx context.Context, event messaging.MessageEvent) (messaging.MessageEvent, error)
// EphemeralSender delivers EphemeralReplies and retracts them after their TTL. // EphemeralSender sends EphemeralReplies and deletes them after their TTL.
// // after defaults to time.After.
// The retraction runs on its own goroutine, so a TTL that has not elapsed
// never holds the turn that sent the reply. after is injected so the TTL
// fires in tests without sleeping; nil selects time.After, which is the
// production shape.
type EphemeralSender struct { type EphemeralSender struct {
after func(time.Duration) <-chan time.Time after func(time.Duration) <-chan time.Time
timeout time.Duration timeout time.Duration
@@ -48,15 +44,9 @@ func NewEphemeralSender(log *slog.Logger, after func(time.Duration) <-chan time.
} }
} }
// Send delivers reply.Event through send. When sender reports the Delete // Send delivers reply.Event and schedules its deletion after reply.TTL when
// capability, the delivered message is retracted once reply.TTL elapses; // sender supports Delete. A send error is returned; nothing is scheduled
// otherwise the reply is left in place and the fact is logged once, at debug // without a message ID or a positive TTL.
// level. A platform that cannot delete must never fail the turn, so the
// degrade returns the send's outcome rather than an error.
//
// A send error is returned unchanged and no retraction is scheduled: there
// is no message to remove. A non-positive TTL or a send that reported no
// message identifier also schedules nothing.
func (e *EphemeralSender) Send(ctx context.Context, sender any, reply messaging.EphemeralReply, send SendFunc) (messaging.MessageEvent, error) { func (e *EphemeralSender) Send(ctx context.Context, sender any, reply messaging.EphemeralReply, send SendFunc) (messaging.MessageEvent, error) {
sent, err := send(ctx, reply.Event) sent, err := send(ctx, reply.Event)
if err != nil { if err != nil {
+2 -6
View File
@@ -1,9 +1,5 @@
// Package status is the operator-facing channel lifecycle ledger: the // Package status tracks channel lifecycle state for the dashboard and
// State/Descriptor/Status vocabulary and the Manager that owns runtime // readiness.
// facts for the dashboard and readiness surfaces. It lives beside the
// channels package rather than inside it so UI-process code can hold the
// types without linking the plugin contract there -- which references the
// gateway runtime.
package status package status
import "sync" import "sync"
+1 -6
View File
@@ -194,12 +194,7 @@ func (g *Gateway) handleWebhook(route *RouteConfig) http.HandlerFunc {
return return
} }
// A rate-limited delivery was dropped before reaching the LLM, not // A rate-limited delivery answers 429 so the source retries.
// completed: it must not be echoed back as a successful "origin" reply
// (chat prose, meant for a human) or 202'd as accepted (indistinguishable
// from a delivered event, so the source would never retry it). 429 lets
// the source back off and retry, the way internal/webhookguard.RateLimiter's
// other callers already respond.
if reply.RateLimited { if reply.RateLimited {
http.Error(w, "rate limited", http.StatusTooManyRequests) http.Error(w, "rate limited", http.StatusTooManyRequests)
return return
+7 -21
View File
@@ -1,20 +1,9 @@
// Package access owns the policy schema, the action vocabulary, how // Package access defines the policy schema, the action vocabulary, policy
// principals and resources are turned into policy entities, and the // entities and the Authorizer contract. The chain is
// Authorizer contract.
// //
// The policy chain is // instance ─▶ org ─▶ workspace ─▶ object
// //
// instance ─▶ org ─▶ workspace ─▶ identity + workflow ─▶ object // The Cedar engine is in internal/infrastructure/access.
//
// and the Cedar implementation lives in internal/infrastructure/access;
// internal/app wires it. Exactly two places call the Authorizer: the
// dashboard and API request path, and dispatch. Every other service verifies
// a credential and never evaluates policy.
//
// The chain's "identity + workflow" level is expressed with object policies:
// an identity or a workflow is one of the objects a policy can attach to
// (event source, secret, identity, binding, workflow), so the stored levels
// are instance, org, workspace and object.
package access package access
import ( import (
@@ -109,12 +98,9 @@ const (
KindEventIngest ResourceKind = "event" KindEventIngest ResourceKind = "event"
) )
// Policy is one stored policy document. Its Text is Cedar policy language // Policy is one stored Cedar policy. LevelInstance has no scope; LevelOrg sets
// (one policy: an effect, a principal/action/resource scope and conditions). // OrgID; LevelWorkspace adds WorkspaceID; LevelObject adds ObjectKind and
// // ObjectID.
// The scope fields say where the policy attaches. LevelInstance policies
// carry none; LevelOrg carries OrgID; LevelWorkspace adds WorkspaceID;
// LevelObject adds ObjectKind and ObjectID.
type Policy struct { type Policy struct {
ID string `json:"id"` ID string `json:"id"`
Level Level `json:"level"` Level Level `json:"level"`
+3 -13
View File
@@ -5,14 +5,8 @@ package access
import "context" import "context"
// Authorizer evaluates the policy chain for one request. Exactly two places // Authorizer evaluates the policy chain for a request. It never fails open:
// call it: the dashboard and // an unparsable stored policy denies its whole level.
// API request path, and dispatch. The implementation is the Cedar engine in
// internal/infrastructure/access.
//
// Authorize never fails open: a stored policy the engine cannot parse makes
// its level deny everything and the decision carries the error; an invalid
// instance policy is a boot failure, not a denial the request path sees.
type Authorizer interface { type Authorizer interface {
// Authorize evaluates instance, org, workspace and object policies for // Authorize evaluates instance, org, workspace and object policies for
// the request. A request is allowed only if every level with policies // the request. A request is allowed only if every level with policies
@@ -21,11 +15,7 @@ type Authorizer interface {
Authorize(p Principal, a Action, r Resource, c Context) Decision Authorize(p Principal, a Action, r Resource, c Context) Decision
} }
// Validator checks one policy against the current schema: Cedar syntax plus // Validator checks a policy's Cedar syntax and entity vocabulary.
// the entity vocabulary this package defines. A policy naming an unknown
// entity type, action or attribute is refused. Every stored policy is
// checked again when archie starts (the engine's construction reports the
// invalid ones).
type Validator interface { type Validator interface {
Validate(p Policy) error Validate(p Policy) error
} }
-5
View File
@@ -1,8 +1,3 @@
// The entities a decision is made about. The domain owns their shape and the
// Cedar vocabulary they are built from (the schema); the engine in
// internal/infrastructure/access turns them into engine entities. This file
// carries no Cedar dependency: the vocabulary is plain constants so the
// domain never links the engine.
package access package access
import ( import (
-7
View File
@@ -1,10 +1,3 @@
// The shipped policies: the four org roles every org carries, and the
// cross-org forbid the engine always enforces
//
// The role policies are Cedar policy text because that is what the engine
// evaluates. They live in the domain so the store seeds them, the reset
// command restores them, and the engine ships the same words regardless of
// which process builds it.
package access package access
import "github.com/samcharles93/archie-core/internal/domain/org" import "github.com/samcharles93/archie-core/internal/domain/org"
+4 -23
View File
@@ -2,16 +2,8 @@ package agent
import "strings" import "strings"
// DefaultSoul is the starter SOUL document this build ships. // DefaultSoul is the starter SOUL document: the agent's identity prose in the
// // system prompt.
// It is deliberately independent of ShippedPersonas: the persona catalogue is
// a style axis that is being retired, while the starter SOUL is the fallback
// identity a user edits. Deleting personas must not delete the fallback.
//
// The document is plain Markdown and becomes the identity slot of the system
// prompt, XML-escaped beneath the invariant sections. It owns the agent's
// name, register and warmth only; it cannot change the rules, tools or runtime
// metadata, so keep it to identity prose.
const DefaultSoul = `# Archie const DefaultSoul = `# Archie
You are Archie, a capable coding and project assistant. Be direct without being You are Archie, a capable coding and project assistant. Be direct without being
@@ -21,23 +13,12 @@ verified. Do not impersonate another assistant, provider, or vendor.
` `
// ShippedSoul returns the SOUL document this build ships. // ShippedSoul returns the SOUL document this build ships.
//
// Exactly one body is shipped, so the seeder recognises only this text as
// untouched scaffolding. A build that supersedes it adds the old body next to
// this one together with the in-place upgrade that consumes it; a branch that
// rewrites a file for matching a template no build ever shipped has no
// producer and must not be kept ahead of one.
func ShippedSoul() string { func ShippedSoul() string {
return DefaultSoul return DefaultSoul
} }
// SoulMatchesShipped reports whether content is the same body as shipped, once // SoulMatchesShipped reports whether content equals shipped after line-ending
// transport noise is normalised away. // and trailing-whitespace normalisation.
//
// Comparison is on normalised content, so a CRLF checkout or an editor that
// left trailing whitespace still matches the template it came from. Only a
// body that is identical to a shipped document after that normalisation is
// eligible for replacement; any other difference is treated as user intent.
func SoulMatchesShipped(content, shipped string) bool { func SoulMatchesShipped(content, shipped string) bool {
return normalizeSoul(content) == normalizeSoul(shipped) return normalizeSoul(content) == normalizeSoul(shipped)
} }
+5 -19
View File
@@ -55,14 +55,8 @@ type Reporter struct {
applied map[string]storecontract.ApplyStatus applied map[string]storecontract.ApplyStatus
} }
// New returns a Reporter for one process, or nil when there is no store to // New returns a Reporter for process, or nil when there is no store or the
// report to or the composition is a process that applies nothing, such as the // process applies nothing. Unknown process names are refused.
// State Store itself.
//
// A name Processes() does not list is refused rather than reported: the reader
// renders the names it knows, so an invented one would vanish from the page
// exactly as a process that never started does. Failing here makes a new
// process declare itself in one place.
func New(process string, store storecontract.ApplyStatusStore, log *slog.Logger) *Reporter { func New(process string, store storecontract.ApplyStatusStore, log *slog.Logger) *Reporter {
if store == nil || process == "" { if store == nil || process == "" {
return nil return nil
@@ -80,12 +74,8 @@ func New(process string, store storecontract.ApplyStatusStore, log *slog.Logger)
} }
} }
// Report records that this process applied version of kind, or failed to. // Report records that this process applied version of kind, or failed to. A
// A failure leaves the recorded version alone: an edit this process rejected // failure keeps the previous version. Errors are logged.
// does not change which version is live in it.
//
// Best-effort by construction. The configuration a report describes has
// already been applied, so a failed report is logged and never returned.
func (r *Reporter) Report(ctx context.Context, kind string, version int64, applyErr error) { func (r *Reporter) Report(ctx context.Context, kind string, version int64, applyErr error) {
if r == nil { if r == nil {
return return
@@ -107,11 +97,7 @@ func (r *Reporter) Report(ctx context.Context, kind string, version int64, apply
r.write(ctx, status) r.write(ctx, status)
} }
// AppliedVersion returns the version last recorded for kind, or 0 when this // AppliedVersion returns the last version recorded for kind, or 0.
// process has reported none. A caller that reports an outcome rather than an
// application -- the plugin directory reconciliation, which reports against
// the plugin-settings version the process is already running -- reads it so a
// clean pass does not reset the version to zero.
func (r *Reporter) AppliedVersion(kind string) int64 { func (r *Reporter) AppliedVersion(kind string) int64 {
if r == nil { if r == nil {
return 0 return 0
+6 -26
View File
@@ -11,11 +11,8 @@ import (
"github.com/samcharles93/archie-core/internal/domain/org" "github.com/samcharles93/archie-core/internal/domain/org"
) )
// Status is the binding lifecycle state. Mirrors telegram's // Status is a binding's state. New bindings are pending_approval; only armed
// dangerousAction / pendingApproval shape: a binding is created // bindings dispatch; any edit returns to pending_approval; Approve arms.
// pending_approval, armed is the only state that evaluates against incoming
// events, any edit drops armed back to pending_approval, and only an
// explicit Approve call moves pending_approval -> armed.
type Status string type Status string
const ( const (
@@ -23,25 +20,13 @@ const (
StatusArmed Status = "armed" StatusArmed Status = "armed"
) )
// Matcher decides which captured events a binding applies to. Source is // Matcher selects the captures a binding applies to, by source path segment.
// the only dimension today -- the path segment the sender POSTs to
// (e.g. "sentry"). Extend with additional predicates if a use case
// demands it; the storage column is plain TEXT so widening is
// non-breaking.
type Matcher struct { type Matcher struct {
Source string `json:"source"` Source string `json:"source"`
} }
// Binding is the runtime-editable entity that ties a matcher, a payload // Binding ties a source matcher, a payload mapping and a workflow together.
// mapping, and a workflow together. Bindings live in the store, not in // Version increments on every update.
// config.toml, so operators can author them from the dashboard while the
// daemon runs. Any number of bindings may share a source: each one applies to
// the event type its mapping belongs to.
//
// Version is bumped on every UpdateBinding so a later edit cannot
// silently rewrite the historical provenance of a task that already
// fired. Signing belongs to the source the matcher names, not to the
// binding (internal/domain/source).
type Binding struct { type Binding struct {
ID string `json:"id"` ID string `json:"id"`
Name string `json:"name"` Name string `json:"name"`
@@ -51,12 +36,7 @@ type Binding struct {
// (CompileFilter). An event it excludes is not dispatched. // (CompileFilter). An event it excludes is not dispatched.
Filter string `json:"filter,omitempty"` Filter string `json:"filter,omitempty"`
Workflow string `json:"workflow"` Workflow string `json:"workflow"`
// Owner and Repo pin a binding to a specific configured repo, so a // Owner and Repo pin the binding to a repo. Both or neither must be set.
// multi-repo deployment can dispatch correctly. Both empty means "no
// pin" -- resolveBindingRepo falls back to the single-configured-repo
// behaviour that predates this field. Setting only one is invalid
// (Validate rejects it): a pin is a complete owner/repo pair or not a
// pin at all, never a half-guess.
Owner string `json:"owner,omitempty"` Owner string `json:"owner,omitempty"`
Repo string `json:"repo,omitempty"` Repo string `json:"repo,omitempty"`
// RepoParam names the mapped parameter holding "owner/name" when the // RepoParam names the mapped parameter holding "owner/name" when the
+3 -5
View File
@@ -23,11 +23,9 @@ func (s InputSource) validate(name string) error {
return nil return nil
} }
// CheckWorkflow checks the binding against the workflow it targets and the // CheckWorkflow validates the binding against its workflow and mapping:
// mapping it reads, as the binding is saved: every assigned input is declared, // inputs declared and assigned with matching types, and a compatible
// every required input is assigned, a parameter exists and its type feeds the // repository.
// input's, a constant has the input's type, and the repository agrees with the
// workflow's repository mode.
func (b Binding) CheckWorkflow(w task.WorkflowInterface, fields []mapping.Field) error { func (b Binding) CheckWorkflow(w task.WorkflowInterface, fields []mapping.Field) error {
byName := make(map[string]mapping.Field, len(fields)) byName := make(map[string]mapping.Field, len(fields))
for _, f := range fields { for _, f := range fields {
+1 -6
View File
@@ -21,12 +21,7 @@ type Activity struct {
Recent []Action Recent []Action
} }
// activityTracker records recent curator activity in memory, fed directly // activityTracker records recent curator activity in memory.
// from the runtime's own emit point (Runtime.emitRun) rather than by
// re-subscribing to the event bus -- the runtime already has the pass
// result in hand, and EventSink is fire-and-forget with no replay. Activity
// resets on daemon restart, same as every other piece of runtime state the
// curator family holds only in memory.
type activityTracker struct { type activityTracker struct {
mu sync.Mutex mu sync.Mutex
data map[string]*Activity data map[string]*Activity
+2 -10
View File
@@ -1,13 +1,5 @@
// Package curator is the curator engine family: long-running agent loops // Package curator runs curators: long-running agent loops that maintain
// that reason over memory and perform small maintenance tasks, rather than // memory, each with a declared interval, tool set and memory engine.
// one hardcoded background job..
//
// A curator is defined by a declared shape (check-in interval, tool set,
// attached memory engine), runs persistently while there is input, and backs
// off to a cooldown when idle. The family follows the strict plugin engine
// rule: a typed contract (CuratorEngine), an owning registry (Registry) with
// start/health/stop and shutdown ordering, and narrow typed host access
// (Registrar) — a curator never receives the daemon or an untyped hook map.
package curator package curator
import ( import (
+1 -5
View File
@@ -1,10 +1,6 @@
package curator package curator
// Definition is a curator definition as data: the declared Manifest plus // Definition is a curator defined as data, run by DefinitionEngine.
// the identity, lifecycle flag, and free-form instructions the manifest
// cannot express. One generic engine (DefinitionEngine) interprets any
// definition -- there is deliberately no catalogue of curator "types" and
// no second authority beside the existing registry.
type Definition struct { type Definition struct {
// Name is the registry key. // Name is the registry key.
Name string Name string
+5 -18
View File
@@ -9,11 +9,8 @@ import (
"github.com/samcharles93/archie-core/internal/tools" "github.com/samcharles93/archie-core/internal/tools"
) )
// Registrar is the narrow typed host access a curator receives at // Registrar is the host access a curator receives, limited to what its
// registration. Only the services the curator's declared shape requires are // manifest declares.
// ever populated in the view the registry binds (see Registry.filter); the
// daemon itself is never part of it. Fields are typed contracts declared
// here — this package never names who implements them.
type Registrar struct { type Registrar struct {
// Log is the curator-scoped diagnostic logger. It is optional so domain // Log is the curator-scoped diagnostic logger. It is optional so domain
// tests and embedders can construct a registrar without a logging sink. // tests and embedders can construct a registrar without a logging sink.
@@ -32,14 +29,8 @@ type Registrar struct {
// Skills is the skill-maintenance capability. Bound when the curator // Skills is the skill-maintenance capability. Bound when the curator
// declares Skills. // declares Skills.
Skills SkillStore Skills SkillStore
// MemoryEngines resolves a named memory engine, for a curator that // MemoryEngines resolves a memory engine by name. Bound only when the
// declared Manifest.MemoryEngine. Bound // manifest declares one.
// only when declared. Like Tools, resolution is by name at call time,
// not a value pre-fetched at Bind: a curator calls
// MemoryEngines.Get(its own Manifest().MemoryEngine), the same trust
// model ToolBuilder.Build(ctx, declared) already uses -- the caller is
// trusted to pass its own declared identifier, not handed a
// pre-scoped instance.
MemoryEngines MemoryEngineSource MemoryEngines MemoryEngineSource
// Conversations is read-only recent conversation history, for a curator // Conversations is read-only recent conversation history, for a curator
// that declared Manifest.Conversations. Bound only when declared. // that declared Manifest.Conversations. Bound only when declared.
@@ -155,11 +146,7 @@ type SessionSummary struct {
type ConversationMessage struct { type ConversationMessage struct {
Role string // "user" or "assistant" Role string // "user" or "assistant"
Content string Content string
// SenderID is the channel-native stable identifier of the party that // SenderID is the sender's channel-native ID, empty for assistant messages.
// sent the message (see messaging.Message.SenderID). Empty for an
// assistant message, and for a channel that carries no per-sender
// identity. A curator derives a session's participant from the
// user-role messages that carry one.
SenderID string SenderID string
At time.Time At time.Time
} }
+7 -20
View File
@@ -32,11 +32,8 @@ type curatorStatus struct {
startErr error startErr error
} }
// Registry is the curator family owner: it controls registration and // Registry owns curator registration and lifecycle. A curator's failure
// discovery, lifecycle (start/health/stop), shutdown ordering, and failure // affects only that curator.
// isolation. A curator failure — a rejected registration, a failing Start, a
// blocking Stop, even a panicking Bind — affects only that curator and is
// reported, never fatal to the daemon or to other curators.
type Registry struct { type Registry struct {
mu sync.Mutex mu sync.Mutex
host Registrar host Registrar
@@ -66,11 +63,7 @@ func NewRegistry(host Registrar) *Registry {
} }
} }
// RecordActivity records one pass's outcome for the named curator so it is // RecordActivity records one pass's outcome for the named curator.
// inspectable at runtime: last run time, action count, and recent actions
// with their reasons. Called by the runtime at the same point it emits the
// curator_run/curator_action events (Runtime.emitRun), so the two views
// never disagree.
func (r *Registry) RecordActivity(name string, at time.Time, actions []Action) { func (r *Registry) RecordActivity(name string, at time.Time, actions []Action) {
r.activity.record(name, at, actions) r.activity.record(name, at, actions)
} }
@@ -81,11 +74,8 @@ func (r *Registry) Activity(name string) (Activity, bool) {
return r.activity.snapshot(name) return r.activity.snapshot(name)
} }
// Register validates the curator's declared shape against the registrar and // Register validates the curator's manifest and binds it to a filtered host
// adds it, binding the curator to a host view filtered to its declared // view. Failures affect only that curator.
// capabilities. Registration fails on nil engines, invalid manifests,
// duplicate names, a declared capability with no host service behind it, or
// a panicking Bind — and a failure affects only that curator.
func (r *Registry) Register(c CuratorEngine) error { func (r *Registry) Register(c CuratorEngine) error {
if isNilEngine(c) { if isNilEngine(c) {
return errors.New("curator: nil engine") return errors.New("curator: nil engine")
@@ -271,11 +261,8 @@ func healthSafely(ctx context.Context, c CuratorEngine) (h Health) {
return c.Health(ctx) return c.Health(ctx)
} }
// Stop stops every started curator in reverse registration order. Curators // Stop stops started curators in reverse order, bounded by ctx, and joins
// whose Start failed are skipped; the call is bounded by ctx — a curator // their errors.
// that ignores cancellation cannot hang the daemon's shutdown beyond the
// caller's deadline, and its error is joined into the result. Stopping a
// registry that never started is a no-op.
func (r *Registry) Stop(ctx context.Context) error { func (r *Registry) Stop(ctx context.Context) error {
r.mu.Lock() r.mu.Lock()
if r.state == stateIdle || r.state == stateStopped { if r.state == stateIdle || r.state == stateStopped {
+4 -15
View File
@@ -32,16 +32,8 @@ type RuntimeConfig struct {
MaxConcurrentPasses int MaxConcurrentPasses int
} }
// Runtime runs the registered curators' loops: one goroutine per curator, // Runtime runs one loop per registered curator, with per-pass timeouts and
// timing driven by the registry's clock (fake-clock testable), waking on // panic recovery. Wake events are best-effort.
// best-effort nudges (the trigger decision belongs to the curator's Check),
// with per-pass timeouts, panic recovery, and bounded shutdown.
//
// Curators are peers, never dependencies: nothing a curator does — a
// blocking pass, a panic, a burst of nudges — can block a chat turn, an
// agent run, or the daemon. Wake events are accelerations; the trigger is a
// deterministic state read at pass time, so a dropped
// nudge only delays a run to the next check-in.
type Runtime struct { type Runtime struct {
registry *Registry registry *Registry
cfg RuntimeConfig cfg RuntimeConfig
@@ -127,11 +119,8 @@ func (rt *Runtime) Nudge(curator string) {
} }
} }
// Stop cancels every loop, waits for in-flight passes to unwind (bounded by // Stop cancels every loop, waits for passes to finish within ctx, then stops
// ctx), then stops the curators' lifecycle in reverse registration order. // the curators in reverse order.
// A pass that ignores cancellation cannot hang shutdown beyond ctx: Stop
// returns ctx.Err once the deadline passes. Stopping a runtime that never
// started is a no-op.
func (rt *Runtime) Stop(ctx context.Context) error { func (rt *Runtime) Stop(ctx context.Context) error {
rt.mu.Lock() rt.mu.Lock()
if !rt.started { if !rt.started {
+2 -9
View File
@@ -7,15 +7,8 @@ import (
"github.com/samcharles93/archie-core/internal/events" "github.com/samcharles93/archie-core/internal/events"
) )
// WakeOnPrimaryInput forwards primary-input events from the in-process bus // WakeOnPrimaryInput nudges the runtime for each bus event of inputKinds
// to the runtime as best-effort nudges. Only the kinds in // until ctx ends or the bus closes. Dropped events only delay a run.
// inputKinds wake curators — the trigger-accounting invariant: curator-
// produced activity (curator_run, curator_action, curator_error, and any
// future derived-write kind) never appears on this path, so a curator's own
// output cannot feed its own trigger. The subscription is bounded and the
// bus drops on overflow, so a slow curator can never backpressure the chat
// publisher; a dropped event only delays a run to the next check-in. The
// forwarder runs until ctx is cancelled or the bus closes.
func WakeOnPrimaryInput(ctx context.Context, bus *events.Bus, rt *Runtime, inputKinds ...string) { func WakeOnPrimaryInput(ctx context.Context, bus *events.Bus, rt *Runtime, inputKinds ...string) {
sub := bus.Subscribe(defaultWakeBuffer) sub := bus.Subscribe(defaultWakeBuffer)
go func() { go func() {
+6 -26
View File
@@ -1,24 +1,9 @@
// Package drain owns the decision logic for external drain requests. // Package drain decides whether a drain marker file applies to the running
// // daemon. A marker is honoured only when its epoch matches the current one.
// A drain is an operator-initiated request for the daemon to stop accepting
// new work and shut itself down gracefully. It arrives out-of-band through a
// marker file (an external trigger such as a maintenance window or a rolling
// deploy writes it) rather than a signal, because a marker survives the phase
// in which the process is between restarts and can be validated against the
// *current* instantiation.
//
// The single source of confusion this package rules out is the stale marker: a
// drain request written before the daemon last restarted must never drain the
// daemon that came up afterwards. That is handled by pairing each marker with
// an instantiation epoch (the OS boot id plus PID 1's start time) and only
// honouring a marker whose epoch matches the current one.
package drain package drain
// Epoch identifies one instantiation of the daemon's process tree. It // Epoch identifies one boot of the process tree: the OS boot id and PID 1's
// combines the OS boot id with PID 1's start time (in clock ticks since // start time.
// boot). Two Epochs are equal only when both parts match, so a marker written
// before a reboot or before a PID 1 restart within the same boot is never
// mistaken for one written against the current instantiation.
type Epoch struct { type Epoch struct {
// BootID is the content of /proc/sys/kernel/random/boot_id, a UUID that // BootID is the content of /proc/sys/kernel/random/boot_id, a UUID that
// changes on every boot. // changes on every boot.
@@ -83,13 +68,8 @@ func (d Decision) String() string {
} }
} }
// Decide returns the drain decision for marker against current. // Decide returns the decision for marker. Nil means none; an empty current
// // epoch or a mismatched marker is stale.
// A nil marker means no request (DecisionNone). An empty current epoch means
// the OS identity facts could not be established, so the request is treated as
// stale -- a daemon that cannot prove the marker is live must not shut itself
// down on it. Only a marker whose epoch exactly matches a non-empty current
// epoch is honoured.
func Decide(current Epoch, marker *Marker) Decision { func Decide(current Epoch, marker *Marker) Decision {
if marker == nil { if marker == nil {
return DecisionNone return DecisionNone
+18 -92
View File
@@ -1,21 +1,5 @@
// Package expr is the CEL expression environment for the EDA playbook engine: // Package expr is the CEL environment for EDA playbook `when` and `args`
// one mechanism for both an action's `when` condition and its `args` values, // expressions, with an `event` root and a per-playbook typed `actions` root.
// per eda-playbook-engine.md's resolved open question 1 (CEL decision).
//
// The environment declares two context roots -- `event` (the triggering
// event's decoded payload, kept dyn by J4) and `actions` (prior actions'
// results keyed by the action's declared id) -- and applies a cost limit to
// every program. `actions` is not a global map: its shape depends on the ids
// one playbook declares and the kind each id runs, so NewEnv takes the
// declared ids and their Go Result struct types and builds a per-playbook
// object type (multi-action-playbooks.md, D3). The playbook loader compiles
// every `when` and `args` value here, so load-time rejection and runtime
// evaluation cannot disagree; the standalone lint command covers the flat
// kind/label binding files, not rich EDA playbook documents.
//
// CEL is non-Turing-complete, side-effect-free, and panic-free by design.
// Anything the schema does not accept is a returned error here -- the
// reject-at-load philosophy of the parent design doc.
package expr package expr
import ( import (
@@ -33,12 +17,8 @@ import (
// resolved doc: tunable, start here; linter and daemon share the same value). // resolved doc: tunable, start here; linter and daemon share the same value).
const DefaultCostLimit = 100_000 const DefaultCostLimit = 100_000
// DeclaredResult is one prior action's result the environment exposes to a // DeclaredResult is a prior action's id and Result type, read as
// later expression. ID is the action's declared id, read as // actions.<ID>.result.<field>.
// `actions.<ID>.result.<field>`; Type is the reflect.Type of that action
// kind's Go Result struct. `module.ModuleRegistry.DecodeResult` is the site
// that converts Invoke's flat result map back into this struct before a later
// expression reads it.
type DeclaredResult struct { type DeclaredResult struct {
ID string ID string
Type reflect.Type Type reflect.Type
@@ -49,14 +29,7 @@ type DeclaredResult struct {
// its fields are never read. // its fields are never read.
type probeResult struct{} type probeResult struct{}
// IsCELFieldName reports whether id can be written as `actions.<id>` in a CEL // IsCELFieldName reports whether id can be written as actions.<id> in CEL.
// expression. It is the authoritative check the playbook loader uses for a
// module action id, replacing a regex approximation of CEL's token rules: it
// compiles a probe expression against a one-field environment declaring the
// id, so the CEL parser and checker decide. CEL keywords (`in`, `true`,
// `false`, `null`) and any other spelling with no field-selection form return
// false; a valid CEL identifier such as `Build` returns true (the loader adds
// its own lowercase policy on top).
func IsCELFieldName(id string) bool { func IsCELFieldName(id string) bool {
if id == "" { if id == "" {
return false return false
@@ -76,17 +49,9 @@ type Env struct {
// Context is what an expression may read at dispatch time. Both roots are // Context is what an expression may read at dispatch time. Both roots are
// read-only from the expression's perspective; CEL enforces this. // read-only from the expression's perspective; CEL enforces this.
type Context struct { type Context struct {
// Event is the triggering event's decoded payload (webhook body, forge // Event is the triggering event's payload, typed dyn.
// issue, schedule tick). Declared dyn because its shape is unknown by
// design (schema-by-example); field-level typing is follow-up work once
// multi-action playbooks exist (per-kind generated Result structs
// declared as CEL types).
Event map[string]any Event map[string]any
// Actions holds prior actions' results keyed by the action's id as // Actions holds prior actions' results by id as {"result": <Result>}.
// declared in the playbook. Each id maps to the per-id wrapper
// `{"result": <KindResult struct>}` built by
// `module.ModuleRegistry.DecodeResult`, so a later expression reads
// `actions.<id>.result.<field>`.
Actions map[string]map[string]any Actions map[string]map[string]any
} }
@@ -118,11 +83,8 @@ func NewEnv(declared ...DeclaredResult) *Env {
return &Env{celEnv: celEnv, costLimit: DefaultCostLimit} return &Env{celEnv: celEnv, costLimit: DefaultCostLimit}
} }
// newResultRegistry registers every declared Result reflect.Type with CEL's // newResultRegistry registers the declared Result types with lower-cased
// native type system, using lower-cased Go field names so `Written` is read // field names.
// as `written`. The registry is both the provider (for the Result struct
// fields) and the adapter (so a Go Result struct value inside the eval map
// adapts to those same fields).
func newResultRegistry(declared []DeclaredResult) (*types.Registry, error) { func newResultRegistry(declared []DeclaredResult) (*types.Registry, error) {
items := make([]any, 0, len(declared)+1) items := make([]any, 0, len(declared)+1)
items = append(items, types.ParseStructField(lowerFieldName)) items = append(items, types.ParseStructField(lowerFieldName))
@@ -138,11 +100,7 @@ func lowerFieldName(f reflect.StructField) string {
return strings.ToLower(f.Name) return strings.ToLower(f.Name)
} }
// nativeResultTypeName is the CEL type name cel-go's native type system // nativeResultTypeName returns the CEL name for a Go type, e.g. log.Result.
// assigns to a reflect.Type (simple package alias + struct name), e.g.
// `log.Result`. It must match the name the native registry registers, because
// the per-id wrapper's `result` field is typed by that name and its fields
// are resolved through the native registry.
func nativeResultTypeName(t reflect.Type) string { func nativeResultTypeName(t reflect.Type) string {
if t.Kind() == reflect.Pointer { if t.Kind() == reflect.Pointer {
t = t.Elem() t = t.Elem()
@@ -154,11 +112,7 @@ func nativeResultTypeName(t reflect.Type) string {
return pkg + "." + t.Name() return pkg + "." + t.Name()
} }
// The `actions` root object type name and the per-id wrapper type namespace. // Type names for the actions root and per-id wrappers.
// Per-id names must live in a reserved namespace (eda.action.<id>): naming a
// wrapper `actions.<id>` makes the checker parse `actions.<id>` as a type
// reference rather than a field selection, which then fails with "type ...
// does not support field selection".
const ( const (
actionsTypeName = "actions" actionsTypeName = "actions"
actionTypePrefix = "eda.action." actionTypePrefix = "eda.action."
@@ -261,11 +215,8 @@ func (p *actionResultProvider) NewValue(structType string, fields map[string]ref
return p.base.NewValue(structType, fields) return p.base.NewValue(structType, fields)
} }
// Compile parses and type-checks a playbook expression string against the // Compile parses and type-checks an expression. Programs are safe for
// declared context. A syntax error, an unknown root (anything other than // concurrent use.
// event/actions), a dynamic `actions` read, or a field typo on a declared
// result is a returned error -- never a panic. The returned Program is safe
// to evaluate concurrently (CEL programs are stateless once compiled).
func (e *Env) Compile(src string) (*Program, error) { func (e *Env) Compile(src string) (*Program, error) {
ast, issues := e.celEnv.Compile(src) ast, issues := e.celEnv.Compile(src)
if issues != nil && issues.Err() != nil { if issues != nil && issues.Err() != nil {
@@ -279,21 +230,8 @@ func (e *Env) Compile(src string) (*Program, error) {
return &Program{prg: prg, actionIDs: ids, resolvable: resolvable, outType: ast.OutputType()}, nil return &Program{prg: prg, actionIDs: ids, resolvable: resolvable, outType: ast.OutputType()}, nil
} }
// actionReferences walks the checked AST once and classifies every read of // actionReferences returns the sorted action ids the expression reads and
// the `actions` context root as either a statically-resolvable action id or // whether every read of `actions` is a field selection.
// not. A root read is an identifier the checker typed as the `actions`
// object: matching on type rather than name keeps a comprehension variable
// that happens to be called `actions` out of the count. Each root read
// consumes exactly one such identifier, so
//
// resolvable = (identCount == staticCount)
//
// where staticCount is the root reads that are a field selection. The
// checker already rejects every other non-static read (a dynamic index,
// `in`, `size`, an undeclared id); the spelling it accepts is a bare
// `actions` value, which compiles but cannot be pinned to an action id at
// load. This walk exists to reject that spelling; the ids return is
// informational. The ids are sorted and de-duplicated.
func actionReferences(ast *cel.Ast) ([]string, bool) { func actionReferences(ast *cel.Ast) ([]string, bool) {
if ast == nil || ast.NativeRep() == nil { if ast == nil || ast.NativeRep() == nil {
return nil, true return nil, true
@@ -368,15 +306,8 @@ func celScalar(t reflect.Type) (*cel.Type, bool) {
} }
} }
// ActionReferences reports the action ids the expression reads from the // ActionReferences returns the action ids the expression reads and whether
// `actions` context root (sorted, de-duplicated) and whether every `actions` // each `actions` read resolves to an id.
// read could be statically resolved to one of those ids. ids is empty when
// the expression reads no prior-action result; resolvable is false when the
// expression reads `actions` in any form that cannot be pinned to a prior
// action id at load. Under the per-playbook object type the checker already
// rejects every dynamic `actions` read, so the only form that still reaches
// here unresolved is a bare `actions` value read; the playbook loader rejects
// that rather than evaluating it as a runtime miss.
func (p *Program) ActionReferences() (ids []string, resolvable bool) { func (p *Program) ActionReferences() (ids []string, resolvable bool) {
if p == nil { if p == nil {
return nil, true return nil, true
@@ -384,12 +315,7 @@ func (p *Program) ActionReferences() (ids []string, resolvable bool) {
return p.actionIDs, p.resolvable return p.actionIDs, p.resolvable
} }
// Eval evaluates the program against a dispatch-time context. A missing // Eval evaluates the program and returns the native Go value.
// field, a wrong type against a dyn value, or an exceeded cost limit is a
// returned error. CEL's own evaluation recovers panics internally (verified
// in cel-go's program.go: Eval wraps evaluation in recover), and its
// returned values implement ref.Val -- unwrapped here to the native Go value
// the caller expects.
func (e *Env) Eval(prg *Program, ctx Context) (any, error) { func (e *Env) Eval(prg *Program, ctx Context) (any, error) {
data := map[string]any{ data := map[string]any{
"event": ctx.Event, "event": ctx.Event,
+1 -8
View File
@@ -1,11 +1,4 @@
// Package log is the schema source for the "log" Module action kind -- the // Package log defines the "log" module kind's Args and Result.
// side-effect-free proof-of-concept kind for the Module position. A Yaegi
// module implementing this kind exports a fixed function name against these
// generated types; the operator's file is the implementation, this package is
// the contract.
//
// This is the hand-written schema. logextract (generated by `go generate`)
// turns it into the Yaegi symbol table the interpreter uses.
package log package log
// SchemaVersion is independent of a playbook's own workflow_version, per // SchemaVersion is independent of a playbook's own workflow_version, per
+9 -43
View File
@@ -1,15 +1,5 @@
// Package module is the Module position of the EDA playbook engine: operator- // Package module loads and invokes EDA module actions, Yaegi-interpreted Go
// installed, in-process, daemon-privileged action implementations, interpreted // files with a fixed entrypoint per kind.
// via Yaegi (same trust tier as PluginDir and SecretEngineDir -- NOT
// repository-supplied task code).
//
// Each module kind has a fixed signature and generated symbol table: load the
// installed source, resolve its typed entrypoint, then call it through the
// panic-safe interpreter boundary.
//
// Each action kind is its own tiny package with its own generated contract
// (internal/domain/eda/module/<kind>), and the registry's internal storage is
// the only place type erasure appears.
package module package module
import ( import (
@@ -90,12 +80,7 @@ func (r *ModuleRegistry) Len() int {
return len(r.kinds) return len(r.kinds)
} }
// KindSchema reports the hand-written Args and Result struct types for a // KindSchema returns a known kind's Args and Result types.
// known kind. A kind is known when it has a registered contract in this
// package's built-in registry (the log kind is the shipped kind), independent
// of whether a module instance is currently loaded from a module directory.
// It is the narrow schema source the playbook loader consumes to type-check
// an action playbook's args and result references at load.
func (r *ModuleRegistry) KindSchema(kind string) (reflect.Type, reflect.Type, bool) { func (r *ModuleRegistry) KindSchema(kind string) (reflect.Type, reflect.Type, bool) {
k, ok := registry[kind] k, ok := registry[kind]
if !ok { if !ok {
@@ -104,11 +89,7 @@ func (r *ModuleRegistry) KindSchema(kind string) (reflect.Type, reflect.Type, bo
return k.argsType, k.resultType, true return k.argsType, k.resultType, true
} }
// Register discovers <dir>/<kind>.go, interprets it against the kind's // Register loads <dir>/<kind>.go and resolves its entrypoint.
// generated symbols, resolves its fixed export, and stores the invoker.
// A missing file, an unreadable file, a resolve failure, or an unknown kind
// is a reported error -- the daemon aborts startup on a broken module
// directory per the established routing-file pattern.
func (r *ModuleRegistry) Register(kind, dir string) error { func (r *ModuleRegistry) Register(kind, dir string) error {
k, ok := registry[kind] k, ok := registry[kind]
if !ok { if !ok {
@@ -211,11 +192,7 @@ func decodeLogArgs(rawArgs map[string]any) (log.Args, error) {
return args, nil return args, nil
} }
// Invoke calls the registered kind with rawArgs and returns the marshaled // Invoke calls kind with rawArgs and returns its result map.
// result. An unregistered kind is a reported error. Invoke is deliberately
// schema-agnostic: it returns the flat map[string]any the kind produces and
// does not re-apply the Result schema. DecodeResult is the single conversion
// site that re-applies it for the typed CEL environment.
func (r *ModuleRegistry) Invoke(ctx context.Context, kind string, rawArgs map[string]any) (map[string]any, error) { func (r *ModuleRegistry) Invoke(ctx context.Context, kind string, rawArgs map[string]any) (map[string]any, error) {
inv, ok := r.kinds[kind] inv, ok := r.kinds[kind]
if !ok { if !ok {
@@ -228,14 +205,8 @@ func (r *ModuleRegistry) Invoke(ctx context.Context, kind string, rawArgs map[st
return res, nil return res, nil
} }
// DecodeResult converts Invoke's flat result map into the kind's registered // DecodeResult converts Invoke's result map into the kind's Result struct.
// Result struct. Invoke stays schema-agnostic and returns map[string]any; this // Unknown, missing or mistyped fields are errors.
// method is the one place the Result schema is re-applied so the value a later
// CEL expression reads is the same Go struct the expression environment typed
// (`actions.<id>.result.<field>`). The map is keyed by the lower-cased Go
// field name, the same spelling expr registers as the CEL field name. An
// unknown field, an absent declared field, or a value that is not already the
// field's type is a reported error.
func (r *ModuleRegistry) DecodeResult(kind string, raw map[string]any) (any, error) { func (r *ModuleRegistry) DecodeResult(kind string, raw map[string]any) (any, error) {
k, ok := registry[kind] k, ok := registry[kind]
if !ok { if !ok {
@@ -244,13 +215,8 @@ func (r *ModuleRegistry) DecodeResult(kind string, raw map[string]any) (any, err
return decodeResultStruct(kind, k.resultType, raw) return decodeResultStruct(kind, k.resultType, raw)
} }
// decodeResultStruct marshals raw into a new value of the kind's Result // decodeResultStruct builds a Result value from raw. Every field must be
// struct type, keyed by the lower-cased Go field name -- the same spelling // present with the exact type.
// expr registers as the CEL field name. Every declared field must be present
// and every value must already carry that field's type: a missing field would
// read as the zero value, and a conversion would change the value's
// representation, so both are reported rather than becoming a quietly wrong
// value in a later expression.
func decodeResultStruct(kind string, t reflect.Type, raw map[string]any) (any, error) { func decodeResultStruct(kind string, t reflect.Type, raw map[string]any) (any, error) {
if t == nil { if t == nil {
return nil, fmt.Errorf("module %s: result schema is not set", kind) return nil, fmt.Errorf("module %s: result schema is not set", kind)
+4 -21
View File
@@ -1,12 +1,4 @@
// Package embedding is the embedding capability: a narrow typed boundary for // Package embedding defines the text embedding contract.
// turning text into vectors, so consumers never depend on a specific provider
// SDK.
//
// Unlike curator and memory (internal/domain/curator, internal/domain/
// memory), a Client has no Lifecycle: it is call-scoped, not long-running,
// the same reasoning internal/domain/image's Provider contract already
// uses -- "is this usable right now" is exactly what Embed returning
// ErrUnavailable already communicates.
package embedding package embedding
import ( import (
@@ -17,12 +9,8 @@ import (
// Sentinel errors every implementation wraps with fmt.Errorf("%w: ...", ...) // Sentinel errors every implementation wraps with fmt.Errorf("%w: ...", ...)
// so callers can errors.Is regardless of backend. // so callers can errors.Is regardless of backend.
var ( var (
// ErrUnavailable means the capability cannot serve right now: no role // ErrUnavailable means embedding is not configured or cannot run; callers
// is configured, the provider is unknown, or its credential could not // degrade.
// be resolved. Per the credential-missing-degrades-not-fatal rule
// (AGENTS.md), this must never prevent the daemon from starting or
// fail an unrelated chat turn -- a caller must degrade (skip the
// content, fall back to free exploration) instead.
ErrUnavailable = errors.New("embedding capability unavailable") ErrUnavailable = errors.New("embedding capability unavailable")
// ErrEmptyInput means Embed was called with no texts. // ErrEmptyInput means Embed was called with no texts.
ErrEmptyInput = errors.New("embedding request has no input text") ErrEmptyInput = errors.New("embedding request has no input text")
@@ -33,11 +21,6 @@ type Vector []float32
// Client is the narrow typed contract every embedding backend implements. // Client is the narrow typed contract every embedding backend implements.
type Client interface { type Client interface {
// Embed returns one Vector per entry in texts, in the same order. // Embed returns one Vector per text, in order.
// Network calls must carry a timeout; a failure is returned as an
// error, never a panic. Callers must treat any non-nil error as
// "skip this batch," matching image.Provider's ErrUnavailable
// convention -- an embedding failure must never crash or fail an
// unrelated caller.
Embed(ctx context.Context, texts []string) ([]Vector, error) Embed(ctx context.Context, texts []string) ([]Vector, error)
} }
+6 -11
View File
@@ -1,9 +1,6 @@
// Package eventtype owns event types: named kinds of event from one source, // Package eventtype defines event types: match rules over a source's headers
// each defined by a match rule over headers and payload. It infers a structural // and payload. It infers signatures, proposes types and refuses overlapping
// signature per capture, groups a source's captures into proposed types, // types on one source.
// evaluates rules, and refuses two types on one source whose rules can match
// the same event. An event that matches no type is unidentified and is never
// dispatched.
package eventtype package eventtype
import ( import (
@@ -134,11 +131,9 @@ func payloadHolds(root any, p PayloadCondition) bool {
return false return false
} }
// Overlaps reports whether some event could satisfy both rules. Two rules are // Overlaps reports whether an event could satisfy both rules. Rules are
// disjoint only when they demand different values of one header, or different // disjoint only when they require different values for one header or a
// values at one payload path outside any array; anything else is treated as // non-array payload path.
// overlapping, which errs towards refusing a save rather than towards an event
// two types both claim.
func Overlaps(a, b Rule) bool { func Overlaps(a, b Rule) bool {
for _, ha := range a.Headers { for _, ha := range a.Headers {
for _, hb := range b.Headers { for _, hb := range b.Headers {
+2 -5
View File
@@ -68,11 +68,8 @@ func Propose(captures []Capture) []Proposal {
return out return out
} }
// separatingRule demands the group's discriminator headers, then, for each // separatingRule requires the group's discriminator headers, plus a path
// sibling those do not already rule out, the presence of the first path the // present in the group but absent from each remaining sibling.
// group has and the sibling lacks. A group whose paths are a subset of a
// sibling's cannot be separated by presence alone; saving it as proposed is
// then refused as an overlap, and the operator edits the rule.
func separatingRule(g Signature, siblings []Signature) Rule { func separatingRule(g Signature, siblings []Signature) Rule {
rule := Rule{Headers: headerConditions(g.Headers)} rule := Rule{Headers: headerConditions(g.Headers)}
paths := slices.Sorted(maps.Keys(g.Paths)) paths := slices.Sorted(maps.Keys(g.Paths))
@@ -1,8 +1,5 @@
// Package harnesssecret is the OAuth token set a credential binding's service // Package harnesssecret defines a credential binding's OAuth token set for
// holds for one org. The setup terminal writes the first capture; the egress // one org.
// proxy overwrites it on every token refresh. It is never a Kit-declared value
// and never resolved through the config secret registry the way an API-key
// binding's SecretRef is -- it is state archie itself captures and mutates.
package harnesssecret package harnesssecret
import ( import (
+2 -15
View File
@@ -1,18 +1,5 @@
// Package health is the readiness-probe contract for archie's operator // Package health defines readiness probes and aggregates their results. A
// surfaces. It defines the probe shape (Name + Check), the resulting // probe is ok or degraded.
// Status vocabulary, and a Registry that runs a fixed set of probes and
// aggregates their results into one report.
//
// Concrete probe implementations live in internal/infrastructure/health;
// composition root wiring lives in internal/app/archied. This package owns
// only the contract and the aggregation rule, so a new subsystem probe never
// has to touch the HTTP surface or the composition root.
//
// The vocabulary is deliberately tiny: a probe is either `ok` (ready for
// work) or `degraded` (not ready -- failed, or a required subsystem report it
// cannot serve). There is no "unknown"; a probe that cannot run must say so
// loudly by reporting degraded, because a readiness consumer treats anything
// other than `ok` as a reason to stop routing work.
package health package health
import "context" import "context"
+4 -18
View File
@@ -62,11 +62,7 @@ type LoginFlow interface {
Exchange(ctx context.Context, code, codeVerifier string) (ProviderSession, error) Exchange(ctx context.Context, code, codeVerifier string) (ProviderSession, error)
} }
// SubjectResolver resolves a verified provider subject to the identity bound to // SubjectResolver resolves a provider subject to its bound identity.
// it. It is deliberately narrower than Repository: authenticating a request
// needs to resolve a subject, not to administer identities, so a consumer that
// only authenticates does not take a dependency on the whole identity CRUD
// surface.
type SubjectResolver interface { type SubjectResolver interface {
// ResolveSubject returns the identity a provider subject is bound to. It is // ResolveSubject returns the identity a provider subject is bound to. It is
// the second binding beside the legacy-name alias: a name archie was // the second binding beside the legacy-name alias: a name archie was
@@ -101,11 +97,7 @@ var (
ErrIdentityInactive = errors.New("identity may not act") ErrIdentityInactive = errors.New("identity may not act")
) )
// Authenticate resolves a presented credential to the identity that may act. // Authenticate verifies rawToken, then resolves it to an identity.
//
// The order is deliberate: the credential is verified by the provider's own
// keys before anything it contains is used, so no field of an unverified token
// can select an identity.
func Authenticate(ctx context.Context, subjects SubjectResolver, verifier Verifier, rawToken string) (Identity, Credential, error) { func Authenticate(ctx context.Context, subjects SubjectResolver, verifier Verifier, rawToken string) (Identity, Credential, error) {
if strings.TrimSpace(rawToken) == "" { if strings.TrimSpace(rawToken) == "" {
return Identity{}, Credential{}, ErrNoCredential return Identity{}, Credential{}, ErrNoCredential
@@ -124,14 +116,8 @@ func Authenticate(ctx context.Context, subjects SubjectResolver, verifier Verifi
return value, credential, nil return value, credential, nil
} }
// Resolve turns an already-verified credential into the identity that may act. // Resolve maps a verified credential to its identity, refusing suspended
// // identities.
// It is the single place the binding and lifecycle rules are applied, so a path
// that verified a credential itself -- the login callback exchanging an
// authorization code -- cannot reach a different verdict from the path that
// verified a presented token. A suspended identity is refused here even though
// its credential verified, because suspension is archie's decision and must not
// depend on the provider withdrawing a token.
func Resolve(ctx context.Context, subjects SubjectResolver, credential Credential) (Identity, error) { func Resolve(ctx context.Context, subjects SubjectResolver, credential Credential) (Identity, error) {
if err := credential.Subject.Validate(); err != nil { if err := credential.Subject.Validate(); err != nil {
return Identity{}, fmt.Errorf("%w: %w", ErrCredentialRejected, err) return Identity{}, fmt.Errorf("%w: %w", ErrCredentialRejected, err)
+2 -11
View File
@@ -95,21 +95,12 @@ func New(id IdentityID, kind Kind, displayName string) (Identity, error) {
return value, nil return value, nil
} }
// FromLegacyName builds the bot identity a configured name denotes -- the // FromLegacyName builds the bot identity for a configured name.
// identity a [[identities]] entry, or the single bot_user, seeds. It is the
// one place a configuration name becomes an identity, so the file path that
// seeds and the store path that creates cannot disagree: both derive through
// New, and therefore through ValidDisplayName.
func FromLegacyName(legacyName string) (Identity, error) { func FromLegacyName(legacyName string) (Identity, error) {
return New(StableID(legacyName), KindBot, legacyName) return New(StableID(legacyName), KindBot, legacyName)
} }
// ValidDisplayName reports whether name can be an identity display name: the // ValidDisplayName reports whether name is non-empty after trimming.
// non-empty-after-trimming rule Validate applies. A configuration loader that
// seeds an identity from a name calls this so the values it accepts and the
// values the store accepts are the same set, rather than two rules on one
// string (a whitespace-only name passed the loader's empty-string test and
// then failed here).
func ValidDisplayName(name string) bool { return strings.TrimSpace(name) != "" } func ValidDisplayName(name string) bool { return strings.TrimSpace(name) != "" }
func (i Identity) Validate() error { func (i Identity) Validate() error {
+1 -10
View File
@@ -1,13 +1,4 @@
// Package image is the image generation capability family: a provider-neutral // Package image defines the image generation provider contract.
// boundary for hosted (gpt-image-2-class) and local GPU backends, so /image
// routing can target either without depending on provider-specific types.
//
// Unlike curator and memory (internal/domain/curator,
// internal/domain/memory), a Provider has no Lifecycle: it is call-scoped,
// not long-running. There is nothing to Start, and "is this usable right
// now" is exactly what Generate/Edit returning ErrUnavailable already
// communicates — a separate Health poll would duplicate that. This package
// defines the contract only; no provider implementation lives here.
package image package image
import ( import (
+2 -6
View File
@@ -150,12 +150,8 @@ func Resolve(fields []Field, payload []byte) (values map[string]any, failures []
return values, failures return values, failures
} }
// pathSegment is a map key (Key set, Index == -1), an array index // pathSegment is a map key, an array index, or Invalid. walk always fails on
// (Index >= 0, Key empty), or Invalid -- a bracket segment whose contents // Invalid.
// were not a plain non-negative integer (e.g. "items[abc]"). walk always
// fails an Invalid segment rather than silently dropping it and matching a
// shorter, unintended path -- a malformed path must read as ReasonMissing,
// never as a different path succeeding by accident.
type pathSegment struct { type pathSegment struct {
Key string Key string
Index int Index int
+9 -44
View File
@@ -1,21 +1,5 @@
// Package memory is the memory engine family: the authoritative store for // Package memory defines the memory engine contract: durable records in
// durable observations, addressed by typed scope. // typed scopes, plus the content scanner. Engines apply no access policy.
//
// One engine, four scopes. A caller names the scopes it may read or write
// (Scope, Subject) and the engine applies no policy of its own: an engine
// that enforced access would need to know about channels, sessions and
// bindings, and every backend would reimplement it. Isolation then falls out
// mechanically, because ScopeAgent{a} and ScopeAgent{b} are different
// storage keys.
//
// The family follows the strict plugin engine rule: a typed contract
// (MemoryEngine) with real domain operations (create, read, update, delete,
// revisions — not just Name/Version), an owning registry (Registry) with
// start/health/stop and shutdown ordering, and narrow typed host access
// (Registrar) — an engine never receives the daemon or an untyped hook map.
//
// This package owns the contract and the family's policy that is independent of
// any backend (the content scanner).
package memory package memory
import ( import (
@@ -82,11 +66,7 @@ const (
ScopeAgentUser ScopeKind = "agent-user" ScopeAgentUser ScopeKind = "agent-user"
) )
// AgentID and IdentityID are opaque. This package never resolves them, // AgentID and IdentityID are opaque.
// canonicalises them, or invents one from a channel: resolution happens
// where the channel's native identity is in hand (the gateway turn path),
// because a channel's sender id is not necessarily a person -- treating one
// as a person would give a URL an identity.
type ( type (
AgentID string AgentID string
IdentityID string IdentityID string
@@ -133,14 +113,8 @@ func (s Scope) Validate() error {
return nil return nil
} }
// Key returns the scope's canonical storage key. Each component is // Key returns the scope's length-prefixed storage key, or "" for an invalid
// length-prefixed, so two different scopes can never share a key even when // scope.
// an id embeds the separator byte — which matters because AgentID and
// IdentityID are opaque and come from channels this package does not
// control.
//
// An invalid scope returns "", which a storage key can never legitimately
// be: callers must Validate first. Every engine path does.
func (s Scope) Key() string { func (s Scope) Key() string {
switch s.Kind { switch s.Kind {
case ScopeGlobal: case ScopeGlobal:
@@ -179,12 +153,8 @@ type Subject struct {
UserID IdentityID UserID IdentityID
} }
// Scopes returns the scopes a read for this subject names, narrowest first: // Scopes returns the subject's readable scopes, narrowest first: agent-user,
// agent-user, agent, user, then global last, because global is the only // agent, user, global.
// scope every subject shares.
//
// The read path hands exactly this set to the engine and the engine unions
// nothing beyond it.
func (s Subject) Scopes() []Scope { func (s Subject) Scopes() []Scope {
return append(s.WritableScopes(), Scope{Kind: ScopeGlobal}) return append(s.WritableScopes(), Scope{Kind: ScopeGlobal})
} }
@@ -206,13 +176,8 @@ func (s Subject) WritableScopes() []Scope {
return scopes return scopes
} }
// Store is the real domain operations every memory backend implements. // Store is a memory backend's record operations. Each takes the record's
// Split out from MemoryEngine so the two concerns (storage vs. // Scope.
// identity/lifecycle) stay separately named and independently testable.
//
// Every method that touches one record takes the record's Scope: a record id
// alone does not locate a scope, and an engine that had to search for one
// would be reimplementing the caller's addressing.
type Store interface { type Store interface {
// Create records one new memory and returns the stored Record, // Create records one new memory and returns the stored Record,
// including the identifier Get/Update/Forget/Revisions later need. // including the identifier Get/Update/Forget/Revisions later need.
+2 -11
View File
@@ -10,21 +10,12 @@ import (
// never names who implements them, and the daemon itself is never part of // never names who implements them, and the daemon itself is never part of
// it. // it.
type Registrar struct { type Registrar struct {
// Events publishes engine activity (writes, forgets, failures) for // Events receives engine activity. Must not block.
// observability. Implementations must be non-blocking and bounded (drop
// on overflow), matching the curator family's EventSink contract, so an
// engine can never apply backpressure to a chat turn or the daemon.
// Always bound.
Events EventSink Events EventSink
// Clock is injectable time. Always bound; nil at construction is // Clock is injectable time. Always bound; nil at construction is
// replaced with the system clock. // replaced with the system clock.
Clock Clock Clock Clock
// Log is the engine-scoped diagnostic logger, optional so domain tests // Log is the engine's logger. Optional.
// and embedders can construct a registrar without a logging sink (the
// curator family's Registrar carries the same field for the same
// reason). An engine emits here what it cannot emit as an event: the
// content scanner's warn level, which allows the write and is expected
// to leave a record of what it saw.
Log *slog.Logger Log *slog.Logger
} }
+4 -10
View File
@@ -31,11 +31,8 @@ type engineStatus struct {
startErr error startErr error
} }
// Registry is the memory family owner: it controls registration and // Registry owns memory engine registration and lifecycle. An engine's
// discovery, lifecycle (start/health/stop), shutdown ordering, and failure // failure affects only that engine.
// isolation. An engine failure — a rejected registration, a failing Start, a
// blocking Stop, even a panicking Bind — affects only that engine and is
// reported, never fatal to the daemon or to other engines.
type Registry struct { type Registry struct {
mu sync.Mutex mu sync.Mutex
host Registrar host Registrar
@@ -183,11 +180,8 @@ func healthSafely(ctx context.Context, e MemoryEngine) (h Health) {
return e.Health(ctx) return e.Health(ctx)
} }
// Stop stops every started engine in reverse registration order. Engines // Stop stops started engines in reverse order, bounded by ctx, and joins
// whose Start failed are skipped; the call is bounded by ctx — an engine // their errors.
// that ignores cancellation cannot hang the daemon's shutdown beyond the
// caller's deadline, and its error is joined into the result. Stopping a
// registry that never started is a no-op.
func (r *Registry) Stop(ctx context.Context) error { func (r *Registry) Stop(ctx context.Context) error {
r.mu.Lock() r.mu.Lock()
if r.state == stateIdle || r.state == stateStopped { if r.state == stateIdle || r.state == stateStopped {
-6
View File
@@ -47,12 +47,6 @@ type DefaultScanner struct{}
// Compile-time check: DefaultScanner implements Scanner. // Compile-time check: DefaultScanner implements Scanner.
var _ Scanner = (*DefaultScanner)(nil) var _ Scanner = (*DefaultScanner)(nil)
// ── Patterns ────────────────────────────────────────────────────────────
//
// These patterns are compiled once at init time. They are intentionally
// broad to catch common variants without being so broad that they
// produce false positives on normal memory content.
var ( var (
promptInjectionPatterns = []*regexp.Regexp{ promptInjectionPatterns = []*regexp.Regexp{
// Override / ignore previous instructions // Override / ignore previous instructions
+3 -10
View File
@@ -9,11 +9,7 @@ import (
"time" "time"
) )
// Candidate is one item eligible for sampling. It is deliberately narrow: // Candidate is an item eligible for sampling.
// an opaque identifier, the timestamp the timestamp-based strategies score
// against, and an open Metadata bag for whatever a future strategy needs
// (e.g. the embedding-backed surprisal strategy's vector) without widening
// this struct for every strategy that comes after wave 1.
type Candidate struct { type Candidate struct {
ID string ID string
At time.Time At time.Time
@@ -29,11 +25,8 @@ type Request struct {
Seed int64 Seed int64
} }
// Sampler selects a subset of candidates to spend a curator pass's agentic // Sampler selects candidates for a curator pass. Implementations must be
// budget on. Every implementation -- the four in this package and the // deterministic.
// future embedding-backed surprisal strategy -- must be
// deterministic given the same candidates and Request: same inputs, same
// output, every time. That is what makes a pass reproducible and testable.
type Sampler interface { type Sampler interface {
// Name identifies the strategy for logging/attribution (e.g. // Name identifies the strategy for logging/attribution (e.g.
// "recency", "random", "all", "staleness", later "surprisal"). // "recency", "random", "all", "staleness", later "surprisal").
+1 -5
View File
@@ -19,11 +19,7 @@ func (recencySampler) Sample(_ context.Context, candidates []Candidate, req Requ
return sorted[:effectiveCap(req.Cap, len(sorted))], nil return sorted[:effectiveCap(req.Cap, len(sorted))], nil
} }
// sortByTime returns a stably-sorted copy of candidates, never mutating the // sortByTime returns a stably sorted copy of candidates by At.
// input. newestFirst true sorts descending by At (recency); false sorts
// ascending (staleness). A stable sort keeps ties in input order, which is
// what makes both strategies deterministic when candidates share a
// timestamp.
func sortByTime(candidates []Candidate, newestFirst bool) []Candidate { func sortByTime(candidates []Candidate, newestFirst bool) []Candidate {
sorted := append([]Candidate(nil), candidates...) sorted := append([]Candidate(nil), candidates...)
slices.SortStableFunc(sorted, func(a, b Candidate) int { slices.SortStableFunc(sorted, func(a, b Candidate) int {
+1 -5
View File
@@ -2,11 +2,7 @@ package sampling
import "context" import "context"
// stalenessSampler is the "staleness proxy" strategy: prefers content that // stalenessSampler prefers the oldest Candidate.At.
// hasn't been touched/reviewed in the longest time, i.e. the smallest
// Candidate.At first. It is a cheap proxy only -- callers decide what
// timestamp At holds (created, updated, or last-reviewed); this is never
// the embedding-based surprisal calculation.
type stalenessSampler struct{} type stalenessSampler struct{}
// NewStaleness builds the "staleness" strategy. // NewStaleness builds the "staleness" strategy.
+3 -17
View File
@@ -1,15 +1,5 @@
// Package scheduling is the ticker engine: the timing half of archied's // Package scheduling decides when scheduled jobs run and with what
// cron/scheduling capability. // concurrency. Storage and delivery are behind JobSource and Runner.
// It owns one job and one job only — deciding *when* a scheduled job runs,
// and with what concurrency — and nothing about where jobs are stored, how
// they are authored, or how their output is delivered.
//
// The split is deliberate. A job store (file-backed, cross-process locked)
// and a delivery router are separate issues in that epic; this package
// declares the two contracts it needs from them (JobSource, Runner) and
// names no implementation. That is what lets the timing behaviour — pool
// semantics, overlap suppression, per-run timeouts, bounded shutdown — be
// tested against a fake clock with no store, no NATS and no model.
package scheduling package scheduling
import ( import (
@@ -78,11 +68,7 @@ func (j Job) Validate() error {
return j.Pool.Validate() return j.Pool.Validate()
} }
// JobSource yields the jobs eligible to run at a given instant. The engine // JobSource returns the jobs due at an instant.
// calls Due once per tick and treats it as authoritative: it applies no
// schedule arithmetic of its own, so a source is free to implement cron
// expressions, fixed intervals or catch-up windows without the engine
// changing.
type JobSource interface { type JobSource interface {
Due(ctx context.Context, now time.Time) ([]Job, error) Due(ctx context.Context, now time.Time) ([]Job, error)
} }
+2 -5
View File
@@ -36,11 +36,8 @@ var cronMacros = map[string]string{
"@hourly": "0 * * * *", "@hourly": "0 * * * *",
} }
// parseCronSpec parses the project's cron dialect: five space-separated // parseCronSpec parses a five-field cron expression or an @ macro. Errors
// fields (minute, hour, day of month, month, day of week) each a wildcard, // wrap ErrInvalidSpec.
// value, range, step (*/n or a-b/n) or comma list of those, or one of the
// @yearly, @annually, @monthly, @weekly, @daily, @midnight and @hourly
// macros. Any failure wraps ErrInvalidSpec.
func parseCronSpec(expr string) (*cronSpec, error) { func parseCronSpec(expr string) (*cronSpec, error) {
spec, err := parseCron(expr) spec, err := parseCron(expr)
if err != nil { if err != nil {
+3 -16
View File
@@ -5,16 +5,8 @@ import (
"time" "time"
) )
// Kind values for JobSpec.Kind: the discriminator that decides which delivery // Job kinds, selecting the delivery runner. Unknown kinds are stored as-is
// runner handles a job. // and refused by the router.
//
// They live beside the field that carries them because they are part of the
// schedules vocabulary an operator writes into the schedules document, a strict
// decoder reads back, and a build that never heard of a kind must reject loudly
// rather than deliver the wrong way. Which runner serves a kind is not this
// package's business: the router in internal/infrastructure/crondelivery owns
// that mapping, which is why an unrecognised kind is stored verbatim rather
// than refused at write time.
const ( const (
// KindChat delivers the job's Payload.Text as a chat message through the // KindChat delivers the job's Payload.Text as a chat message through the
// deployment's channel. It is the default: an empty Kind means KindChat, // deployment's channel. It is the default: an empty Kind means KindChat,
@@ -44,12 +36,7 @@ type JobSpec struct {
// Detail is a human-readable label rendered on events. // Detail is a human-readable label rendered on events.
Detail string `json:"detail,omitempty"` Detail string `json:"detail,omitempty"`
// Kind selects which delivery runner handles this job. Empty means // Kind selects the delivery runner. Empty means KindChat.
// KindChat, so a job written before this field existed keeps
// delivering as a chat message. This package does not interpret the
// value: an unrecognised kind is stored verbatim and refused by the
// delivery router, which is the one place the mapping from kind to
// runner lives.
Kind string `json:"kind,omitempty"` Kind string `json:"kind,omitempty"`
// Schedule decides when this job is due. See schedule.go for the // Schedule decides when this job is due. See schedule.go for the
+12 -35
View File
@@ -6,16 +6,8 @@ import (
"time" "time"
) )
// Duration is a schedule interval as the document writes it: the human string // Duration is a schedule interval written as a duration string. It also
// time.ParseDuration reads, never a nanosecond count. It reads the count too, // reads a nanosecond count.
// because every schedule stored before this shape existed carries one -- both in
// the control plane's schedules resource and in this package's own jobs table,
// which persists the spec as JSON.
//
// The type is deliberately local, as config.Duration is for the file document
// and channelDuration is in internal/app/controlplane: each document owns its own
// wire form, and what is actually worth unifying later is the legacy-count
// tolerance rather than the tag shape.
type Duration time.Duration type Duration time.Duration
func (d Duration) MarshalJSON() ([]byte, error) { func (d Duration) MarshalJSON() ([]byte, error) {
@@ -77,21 +69,15 @@ type Schedule struct {
Start time.Time `json:"start"` Start time.Time `json:"start"`
} }
// Schedule kinds the store recognises. Interval and Cron have full // Schedule kinds. MarkRun on an unsupported kind returns
// next-run arithmetic; Once is accepted at Create / fires at Due exactly // ErrScheduleUnsupported.
// once, but has no next-run arithmetic for MarkRun (one-shot by
// definition). MarkRun on a kind this build does not implement returns
// ErrScheduleUnsupported rather than silently advancing next_run.
const ( const (
// ScheduleInterval fires every Interval after the last successful run // ScheduleInterval fires every Interval after the last successful run
// (or after Start, if never run). The simplest recurring schedule. // (or after Start, if never run). The simplest recurring schedule.
ScheduleInterval = "interval" ScheduleInterval = "interval"
// ScheduleCron fires at the next moment matching a 5-field cron // ScheduleCron fires at the next cron match after the last run, in that
// expression (or one of the @ macros) after the last successful // run's zone. Day-of-month and day-of-week are ANDed.
// run, computed in the zone of that run time. The dialect (cron.go)
// ANDs day-of-month with day-of-week instead of Vixie cron's OR: "0 0 1 * 1" means only Monday the 1st,
// not "the 1st or any Monday".
ScheduleCron = "cron" ScheduleCron = "cron"
// ScheduleOnce fires once at the configured At time. Subsequent // ScheduleOnce fires once at the configured At time. Subsequent
@@ -133,11 +119,8 @@ func (s Schedule) resolve() Schedule {
return s return s
} }
// firstRun returns when the job should fire the very first time it has // firstRun returns a never-run job's first fire time: Start (or now) plus
// never run before. For Interval, it is Start + Interval (or now + Interval // Interval, At for Once, or the first cron match after Start (or now).
// when Start is zero, so a freshly-created job with no Start still has a
// finite next-run). For Once, it is At. For Cron, it is the first matching
// minute strictly after Start (or after now when Start is zero).
func (s Schedule) firstRun(now time.Time) (time.Time, error) { func (s Schedule) firstRun(now time.Time) (time.Time, error) {
switch s.resolve().Kind { switch s.resolve().Kind {
case ScheduleInterval: case ScheduleInterval:
@@ -171,11 +154,8 @@ func (s Schedule) firstRun(now time.Time) (time.Time, error) {
// the parser's field ranges cannot reject — exhausts the scan. // the parser's field ranges cannot reject — exhausts the scan.
const cronHorizon = 5 * 365 * 24 * time.Hour const cronHorizon = 5 * 365 * 24 * time.Hour
// nextCronRun returns the first wall-clock minute in the location of from // nextCronRun returns the first minute after from's minute, in from's
// at which sched is due, strictly after the minute containing from — the // location, at which sched is due.
// minute that just fired is never its own successor. Whole months and
// hours that cannot match are skipped, so even a sparse expression costs
// a handful of iterations per year scanned.
func nextCronRun(sched *cronSpec, from time.Time) (time.Time, error) { func nextCronRun(sched *cronSpec, from time.Time) (time.Time, error) {
t := from.Truncate(time.Minute).Add(time.Minute) t := from.Truncate(time.Minute).Add(time.Minute)
for limit := from.Add(cronHorizon); t.Before(limit); { for limit := from.Add(cronHorizon); t.Before(limit); {
@@ -201,11 +181,8 @@ func (s Schedule) NextRun(lastRun time.Time) (time.Time, error) { return s.nextR
func (s Schedule) Resolved() Schedule { return s.resolve() } func (s Schedule) Resolved() Schedule { return s.resolve() }
// nextRun returns when the job should fire after a successful run at // nextRun returns the next fire time after a successful run at lastRun. Once
// lastRun. It is the engine-side counterpart to firstRun: every MarkRun // returns an error.
// advances next_run through this function. Interval and Cron are fully
// implemented; Once deliberately fails (there is no recurring next run)
// so a silently-wrong value cannot reach the ticker.
func (s Schedule) nextRun(lastRun time.Time) (time.Time, error) { func (s Schedule) nextRun(lastRun time.Time) (time.Time, error) {
switch s.resolve().Kind { switch s.resolve().Kind {
case ScheduleInterval: case ScheduleInterval:
+7 -27
View File
@@ -97,20 +97,9 @@ func (c EngineConfig) withDefaults() EngineConfig {
return c return c
} }
// Engine is the ticker engine: one loop that asks the source what is due at // Engine asks the source what is due each tick and dispatches each job to
// each tick and dispatches each due job to the pool it declares. // its pool. A job never overlaps itself, and the sequential and parallel
// // pools are independent. Errors, panics and timeouts are reported as events.
// Two invariants make the timing safe to reason about:
//
// - A job never overlaps itself. While a run is queued or in flight, later
// ticks reporting the same ID are skipped, not stacked. A job slower than
// the tick interval therefore runs back-to-back, never fanned out.
// - The pools do not interfere. A blocked sequential job cannot delay a
// parallel one, and a saturated parallel cap cannot delay the sequential
// worker — they are separate dispatch paths sharing only the tick.
//
// Every failure is contained: a source error, a job error, a job panic and a
// job timeout are each reported as an event and leave the loop running.
type Engine struct { type Engine struct {
source JobSource source JobSource
runner Runner runner Runner
@@ -160,14 +149,8 @@ func (e *Engine) MaxParallel() int { return e.cfg.MaxParallel }
// JobTimeout reports the resolved per-run timeout. // JobTimeout reports the resolved per-run timeout.
func (e *Engine) JobTimeout() time.Duration { return e.cfg.JobTimeout } func (e *Engine) JobTimeout() time.Duration { return e.cfg.JobTimeout }
// Start launches the tick loop and the sequential worker. // Start launches the tick loop and the sequential worker. An engine can be
// // started only once.
// An engine is single-use: starting one that is already started, or that has
// been stopped, is an error. Restarting is refused rather than supported
// because Stop leaves the dropped sequential backlog and the claims of runs
// it did not wait for behind — a restarted engine would re-run stale queued
// jobs and permanently suppress the jobs still marked claimed. Build a new
// engine instead; it is a struct, not a resource.
func (e *Engine) Start(ctx context.Context) error { func (e *Engine) Start(ctx context.Context) error {
e.mu.Lock() e.mu.Lock()
defer e.mu.Unlock() defer e.mu.Unlock()
@@ -194,11 +177,8 @@ func (e *Engine) Start(ctx context.Context) error {
return nil return nil
} }
// Stop halts ticking, drops any queued-but-unstarted runs, and waits for // Stop halts ticking, drops queued runs and waits for running ones within
// in-flight runs to finish, bounded by ctx. If ctx expires first, in-flight // ctx, then cancels them. Stopping an unstarted engine is a no-op.
// runs are cancelled and ctx's error is returned — a Runner that ignores
// cancellation can still outlive Stop, which is why the deadline is the
// caller's to set. Stopping an engine that never started is a no-op.
func (e *Engine) Stop(ctx context.Context) error { func (e *Engine) Stop(ctx context.Context) error {
e.mu.Lock() e.mu.Lock()
if !e.started { if !e.started {
+12 -41
View File
@@ -68,14 +68,8 @@ type ActionPayload struct {
RetryMode taskstate.RetryMode RetryMode taskstate.RetryMode
} }
// Actor is the identity that performed an action, and the principal whose // Actor is who performed an action and the principal whose authority allowed
// authority permitted it. // it. An empty Principal means unattributed.
//
// The two are separate fields because an agent acting under a person's standing
// approval is not the same fact as a person acting: a record that collapsed
// them would answer "who approved this" with the wrong identity. An empty
// Principal means UNATTRIBUTED -- no authority was recorded, which is a
// different fact from the actor authorising itself.
type Actor struct { type Actor struct {
Identity identity.IdentityID Identity identity.IdentityID
Kind identity.Kind Kind identity.Kind
@@ -183,12 +177,8 @@ type Store interface {
RespondReviewGate(context.Context, int64, string, string, bool, int) error RespondReviewGate(context.Context, int64, string, string, bool, int) error
ArchiveTask(context.Context, int64, string, events.Event) (int64, error) ArchiveTask(context.Context, int64, string, events.Event) (int64, error)
InsertEvent(context.Context, events.Event) (int64, error) InsertEvent(context.Context, events.Event) (int64, error)
// CancelExecution is the one cancel path: // CancelExecution cancels the execution and its open steps in one
// the store // transaction.
// records the cancellation -- every non-terminal step of the current
// attempt plus the execution's own move to `to` -- in one transaction.
// The service then cancels the in-memory context that was delivering the
// run; a worker's next step write fails ErrStaleTransition and stops.
CancelExecution(context.Context, int64, string, string) ([]int64, error) CancelExecution(context.Context, int64, string, string) ([]int64, error)
} }
@@ -206,18 +196,9 @@ type Service struct {
Warn func(string, ...any) Warn func(string, ...any)
} }
// Apply scopes chat requests to an identity. A nil scope denotes a caller // Apply runs action on task id. A nil scope is a dashboard caller acting
// authenticated across identities, which is the dashboard's own credential; // across identities; otherwise scope limits which tasks may be acted on. res
// scope limits which task a chat identity may act on, and never says who acted. // is the action's payload.
//
// The actor is not derived from scope: scope is which tasks a caller may touch,
// actor is who touched one, and the two are only equal by coincidence.
//
// res is the per-action payload (ActionPayload): the operator's instruction
// and finding selection for approve and rereview, the worktree mode for
// retry, and empty for every other action and for the chat surfaces that
// carry no such syntax. Both the dashboard and chat reach the same apply, so
// one operator intent cannot be recorded as two different decisions.
func (s Service) Apply(ctx context.Context, scope *string, actor Actor, id int64, action taskstate.Action, res ActionPayload) error { func (s Service) Apply(ctx context.Context, scope *string, actor Actor, id int64, action taskstate.Action, res ActionPayload) error {
task, err := s.Store.TaskByID(ctx, id) task, err := s.Store.TaskByID(ctx, id)
if err != nil { if err != nil {
@@ -288,16 +269,9 @@ func (s Service) apply(ctx context.Context, task *Task, actor Actor, action task
} }
} }
// applyApprove is the one approval path, for both the review gate and the // applyApprove approves a waiting task. With a gate offer it records the
// human-decision waits that predate it. // answer on the offer; otherwise it requeues under the workflow the wait
// // names.
// A task carrying a gate offer gets the answer recorded on that offer in the
// guarded response write: the resumed run posts the recorded review filtered by
// the operator's selection, which is the only way "post the findings the
// operator selected" can mean the findings they saw. A task with no gate has no
// review to answer, so the approval is the plain release of waiting work; it
// requeues under the workflow the wait names -- which feasibility sets to
// implement before it waits -- never a name this handler hardcodes.
func (s Service) applyApprove(ctx context.Context, task *Task, actor Actor, o outcome, res ActionPayload) (outcome, error) { func (s Service) applyApprove(ctx context.Context, task *Task, actor Actor, o outcome, res ActionPayload) (outcome, error) {
o.event.Kind, o.event.Detail = approvedKind(actor), actor.describe("approved") o.event.Kind, o.event.Detail = approvedKind(actor), actor.describe("approved")
gate, ok := workflowtask.DecodeReviewGate(task.ReviewGate) gate, ok := workflowtask.DecodeReviewGate(task.ReviewGate)
@@ -318,11 +292,8 @@ func (s Service) applyApprove(ctx context.Context, task *Task, actor Actor, o ou
return o, nil return o, nil
} }
// applyRereview records the operator's instructions and requeues the review // applyRereview records the operator's instructions and requeues the review.
// phases. It is refused, as a conflict, for a task with no gate offer and for // It conflicts when there is no gate offer or the cap is reached.
// one at the cap: in both cases the task stays waiting and nothing is written.
// The offer's findings are cleared, because the resumed run recomputes them;
// the instructions are what reach the recomputation.
func (s Service) applyRereview(ctx context.Context, task *Task, actor Actor, o outcome, res ActionPayload) (outcome, error) { func (s Service) applyRereview(ctx context.Context, task *Task, actor Actor, o outcome, res ActionPayload) (outcome, error) {
gate, ok := workflowtask.DecodeReviewGate(task.ReviewGate) gate, ok := workflowtask.DecodeReviewGate(task.ReviewGate)
if !ok || !gate.Offered() { if !ok || !gate.Offered() {
+1 -12
View File
@@ -1,12 +1,5 @@
package workintake package workintake
// This file is the single definition of what a dispatch trigger means: which
// triggers match on a label, and whether a concrete issue (its labels and
// assignees) is eligible work under a trigger. The daemon's poller and the
// forge webhook intake both consult it, so the two cannot drift -- the
// empty-label guard here is the one that previously regressed (3209a1f: an
// empty label matches every open issue via the forge API).
import ( import (
"slices" "slices"
"strings" "strings"
@@ -40,11 +33,7 @@ func containsLabel(labels []string, needle string) bool {
return slices.Contains(labels, needle) return slices.Contains(labels, needle)
} }
// containsAssignee matches logins case-insensitively: GitHub usernames are // containsAssignee matches logins case-insensitively.
// unique case-insensitively, and AssignedIssues' server-side assignee filter
// matches the same way -- an exact-case comparison here would silently miss
// what the poller finds whenever the configured bot_user's case differs from
// the login GitHub reports on the event.
func containsAssignee(assignees []string, botUser string) bool { func containsAssignee(assignees []string, botUser string) bool {
return slices.ContainsFunc(assignees, func(a string) bool { return slices.ContainsFunc(assignees, func(a string) bool {
return strings.EqualFold(a, botUser) return strings.EqualFold(a, botUser)
+4 -17
View File
@@ -1,14 +1,5 @@
// Package workintake owns the promotion of a discovered external issue into // Package workintake turns discovered issues into task envelopes and defines
// durable, workflow-backed work. // their routing kinds and subjects.
//
// It owns the vocabulary of that promotion -- the task envelope, its routing
// kind, and the subjects it is addressed to -- because the domain that defines
// a message's meaning owns its schema. These previously lived in the NATS
// package, which made the transport responsible for knowing what a unit of work
// was
//
// This package names no broker. It produces and consumes bytes; carrying
// them is internal/eventbus's job.
package workintake package workintake
import ( import (
@@ -107,12 +98,8 @@ func (t TaskEnvelope) Ref() string {
return t.Owner + "/" + t.Repo + "#" + strconv.Itoa(t.Number) return t.Owner + "/" + t.Repo + "#" + strconv.Itoa(t.Number)
} }
// IdempotencyKey identifies this issue for delivery deduplication, so // IdempotencyKey identifies this issue for dedup:
// rediscovering it on a later poll does not enqueue the same work twice. The // org/identity/owner/repo/number.
// key is org/identity/owner/repo/number: the poller and the webhook receiver
// resolve the org and identity before publishing, so the same issue delivered
// both ways still gives one key, and the State Store's task uniqueness uses the
// same fields. This method is the one place that shape is produced.
func (t TaskEnvelope) IdempotencyKey() string { func (t TaskEnvelope) IdempotencyKey() string {
return dedupKeyPrefix + string(t.org()) + "/" + t.Identity + "/" + return dedupKeyPrefix + string(t.org()) + "/" + t.Identity + "/" +
t.Owner + "/" + t.Repo + "/" + strconv.Itoa(t.Number) t.Owner + "/" + t.Repo + "/" + strconv.Itoa(t.Number)
+3 -29
View File
@@ -18,12 +18,7 @@ const (
SubjectTaskWildcard = "archie.task.>" SubjectTaskWildcard = "archie.task.>"
) )
// SubjectReactionWildcard matches every reaction subject under archie.reaction. // SubjectReactionWildcard matches every reaction subject.
// Reactions are producer-only fan-out events
// delivered on a separate
// LimitsPolicy stream, so every registered consumer sees every matching event
// -- unlike the work-queue ARCHIE_TASKS stream, where one consumer claims each
// message.
const SubjectReactionWildcard = "archie.reaction.>" const SubjectReactionWildcard = "archie.reaction.>"
// ErrUnknownKind reports a kind with no subject. Routing it to the default // ErrUnknownKind reports a kind with no subject. Routing it to the default
@@ -31,12 +26,6 @@ const SubjectReactionWildcard = "archie.reaction.>"
var ErrUnknownKind = errors.New("workintake: unknown task kind") var ErrUnknownKind = errors.New("workintake: unknown task kind")
// Kind is the routing category an issue's labels select. // Kind is the routing category an issue's labels select.
//
// It is the single axis both the workflow registry and the task subjects
// route on. The label table was once written twice -- a switch in
// workflow.Route and a subject lookup in the NATS package -- so adding a
// label meant remembering both, and the transport had to know what a forge
// label was.
type Kind string type Kind string
const ( const (
@@ -95,11 +84,7 @@ func KindForLabels(labels []string) Kind {
return KindDefault return KindDefault
} }
// KindsForLabels returns every recognised kind in label order. // KindsForLabels returns every recognised kind, in label order.
//
// Workflow routing needs the full ordered set rather than just the first:
// when a task is labelled "bug,feature" and no "tdd" workflow is registered,
// it must still fall through to "feasibility" rather than to the default.
func KindsForLabels(labels []string) []Kind { func KindsForLabels(labels []string) []Kind {
var kinds []Kind var kinds []Kind
for _, label := range labels { for _, label := range labels {
@@ -110,18 +95,7 @@ func KindsForLabels(labels []string) []Kind {
return kinds return kinds
} }
// labelValue reduces a forge label to the value labelKinds is keyed on. // labelValue returns the part of a label after its last "::".
//
// Forges namespace labels by convention ("type::feature", "priority::medium")
// and the namespace is the issue tracker's own taxonomy, not part of the
// routing vocabulary, so the value after the last "::" is what identifies a
// kind. Matching the bare string alone meant a repo that namespaces its
// labels -- which this one does -- never matched any kind, and every task
// fell through kind routing to the content-aware fallback in Route.
//
// The namespace itself is deliberately not checked: a closed three-value
// vocabulary (bug, feature, bootstrap) is specific enough that a label ending
// in one of them means that kind whatever the tracker files it under.
func labelValue(label string) string { func labelValue(label string) string {
trimmed := strings.TrimSpace(label) trimmed := strings.TrimSpace(label)
if i := strings.LastIndex(trimmed, "::"); i >= 0 { if i := strings.LastIndex(trimmed, "::"); i >= 0 {
+2 -19
View File
@@ -1,20 +1,3 @@
// Package eventbus is the broker-neutral messaging contract. // Package eventbus is the broker-neutral messaging contract. Payloads are
// // opaque and subjects are plain strings.
// It defines only the messaging behaviour Archie requires: publication,
// subscription, request/reply, and delivery outcomes. It names no broker.
// NATS subjects, JetStream configuration, consumer groups, acknowledgement
// mechanics, reconnection and serialization live in
// internal/infrastructure/eventbus/nats, which implements these interfaces.
//
// # The bus does not own message meaning
//
// This package deliberately transports opaque payloads. Message schemas
// belong to the domain that defines them -- work intake owns its task
// envelope, agent execution owns its request and response types -- and each
// domain owns the subjects it addresses. A previous version of the NATS
// package exported a TaskEnvelope type and a PublishTask method, which made
// the transport responsible for knowing what a unit of work was.
//
// Subjects are plain strings here. Constraining their syntax would encode one
// broker's addressing rules into the contract.
package eventbus package eventbus
+2 -7
View File
@@ -45,13 +45,8 @@ type Publisher interface {
// Publish sends payload to subject. // Publish sends payload to subject.
Publish(ctx context.Context, subject string, payload []byte) error Publish(ctx context.Context, subject string, payload []byte) error
// PublishUnique sends payload to subject carrying an idempotency key. // PublishUnique publishes payload with an idempotency key; repeats within
// Republishing the same key within the implementation's deduplication // the dedup window are dropped.
// window is suppressed.
//
// This is a required semantic rather than a broker detail: work intake
// rediscovers the same issue on every poll, so at-least-once delivery
// without deduplication would enqueue it repeatedly.
PublishUnique(ctx context.Context, subject, idempotencyKey string, payload []byte) error PublishUnique(ctx context.Context, subject, idempotencyKey string, payload []byte) error
} }
+19 -66
View File
@@ -15,12 +15,8 @@ const (
KindTaskQueued = "task_queued" KindTaskQueued = "task_queued"
KindStageStart = "stage_start" KindStageStart = "stage_start"
KindStageFinish = "stage_finish" // data: duration_ms, error KindStageFinish = "stage_finish" // data: duration_ms, error
// KindAgentFinish carries the stage's token economics as well as its // KindAgentFinish carries the stage outcome and token usage. The breakdown
// outcome: tokens is the run total (agentexec.Result.TokensUsed) and the // fields are optional.
// 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 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 // KindToolCall marks one completed tool invocation during an agent stage
// run. Only emitted for runners that execute in the same process as their // run. Only emitted for runners that execute in the same process as their
@@ -37,26 +33,14 @@ const (
// seeing, because it explains why a task changed course. // seeing, because it explains why a task changed course.
KindHumanApproved = "human_approved" KindHumanApproved = "human_approved"
KindHumanRejected = "human_rejected" KindHumanRejected = "human_rejected"
// KindAgentApproved and KindAgentRejected record that an agent performed // KindAgentApproved and KindAgentRejected record an agent's action.
// 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" KindAgentApproved = "agent_approved"
KindAgentRejected = "agent_rejected" KindAgentRejected = "agent_rejected"
// KindTaskApproved and KindTaskRejected record an approval or rejection that // KindTaskApproved and KindTaskRejected record an unattributed approval or
// archie cannot attribute to anyone: the request carried no identity archie // rejection.
// 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" KindTaskApproved = "task_approved"
KindTaskRejected = "task_rejected" KindTaskRejected = "task_rejected"
// KindHumanRereviewed, KindAgentRereviewed and KindTaskRereviewed record // Re-review requests, by human, agent or unattributed.
// the operator asking the review gate for a re-review. The answer is
// neither an approval nor a rejection, and recording it as either would
// make the timeline claim a verdict the operator did not give. They follow
// the same actor/agent/task attribution split as the approved and rejected
// trios above.
KindHumanRereviewed = "human_rereviewed" KindHumanRereviewed = "human_rereviewed"
KindAgentRereviewed = "agent_rereviewed" KindAgentRereviewed = "agent_rereviewed"
KindTaskRereviewed = "task_rereviewed" KindTaskRereviewed = "task_rereviewed"
@@ -71,24 +55,13 @@ const (
KindWorkRequestSubmitted = "work_request_submitted" KindWorkRequestSubmitted = "work_request_submitted"
KindLog = "log" // data: level, msg KindLog = "log" // data: level, msg
// KindChangesCaptured records the change one attempt produced, read off // KindChangesCaptured records one attempt's change at commit or push time.
// the worktree at the moment it was committed or pushed, plus a final // data: schema, owner, repo, base, branch, head_sha, base_sha, pr_number,
// capture once OpenPR knows the number. It is durable // captured_after, files[], totals, truncated.
// 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" KindChangesCaptured = "changes_captured"
// KindConfigCaptured records the effective configuration one attempt ran // KindConfigCaptured records the configuration one attempt ran with. data:
// under, captured where it is materialised for the dispatch. It is durable // schema and document (the dispatch's config.TaskConfig as JSON).
// 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" KindConfigCaptured = "config_captured"
// Curator family activity. Curator runs ride // Curator family activity. Curator runs ride
@@ -98,11 +71,8 @@ const (
KindCuratorAction = "curator_action" // data: curator, type, detail, reason KindCuratorAction = "curator_action" // data: curator, type, detail, reason
KindCuratorError = "curator_error" // data: curator, phase, err KindCuratorError = "curator_error" // data: curator, phase, err
// Scheduled-job activity from the ticker engine // Scheduled job activity. data: job, pool, duration_ms (run); job, pool,
// (internal/domain/scheduling). A scheduled run has no task and no chat // phase, err (error).
// 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" KindJobRun = "job_run"
KindJobError = "job_error" KindJobError = "job_error"
@@ -112,12 +82,8 @@ const (
// trigger. data: session, channel. // trigger. data: session, channel.
KindTurnCompleted = "turn_completed" KindTurnCompleted = "turn_completed"
// EDA edit activity (bindings and mappings on the captures store). Each // Binding and mapping edits. data: id, action (create, update, approve,
// successful write on the State Store's binding and mapping tables emits one // delete).
// 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" KindBindingChanged = "binding_changed"
KindMappingChanged = "mapping_changed" KindMappingChanged = "mapping_changed"
@@ -136,11 +102,8 @@ const (
// one; a wait:false callee reports on its own run. // one; a wait:false callee reports on its own run.
KindWorkflowCallFinished = "workflow_call_finished" KindWorkflowCallFinished = "workflow_call_finished"
// KindUpdateReport carries the phase-2 outcome of a dashboard-initiated // KindUpdateReport is a dashboard update's post-restart outcome. data:
// update -- whether the restarted daemon came back up healthy and on // health_check, rolled_back, confirmed, drift, unverified.
// the version it claimed, relayed once on the boot that finds the
// pending report left by the update watchdog.
// data: health_check, rolled_back, confirmed, drift, unverified.
KindUpdateReport = "update_report" KindUpdateReport = "update_report"
) )
@@ -167,19 +130,9 @@ type Event struct {
Issue int `json:"issue,omitempty"` Issue int `json:"issue,omitempty"`
Workflow string `json:"workflow,omitempty"` Workflow string `json:"workflow,omitempty"`
Stage string `json:"stage,omitempty"` Stage string `json:"stage,omitempty"`
// Attempt attributes the event to one run of the task. Zero means // Attempt is the task attempt; 0 means unattributed.
// 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"` Attempt int `json:"attempt"`
// ActorID is the identity that performed the action this event records, // ActorID is the identity that acted; empty means no actor is claimed.
// 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"` ActorID string `json:"actor_id,omitempty"`
// ActorKind is the acting identity's kind, kept beside ActorID so a reader // 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 // can tell an agent's action from a person's without resolving the identity
+7 -37
View File
@@ -149,12 +149,7 @@ type Review struct {
// inline comments are flat under a review, so it is 0 there. // inline comments are flat under a review, so it is 0 there.
type ReviewComment struct { type ReviewComment struct {
ID int64 ID int64
// ReviewID is the review this comment belongs to. It is what lets a // ReviewID is the review this comment belongs to; 0 for a standalone comment.
// comment be collected into its review's remediation unit instead of
// starting one of its own (pr-review-remediation.md decision 5); a
// standalone comment carries 0. GitHub carries it on the comment;
// Gitea's flat comment list is walked per review, so the mapping comes
// from the walk.
ReviewID int64 ReviewID int64
Author string Author string
Body string Body string
@@ -164,13 +159,7 @@ type ReviewComment struct {
CreatedAt time.Time CreatedAt time.Time
} }
// PullRequestReviewReader reads review activity on an existing PR. Forge // PullRequestReviewReader reads review activity on a PR newer than sinceID.
// implementations that cannot read reviews (the noop forge) do not implement
// it; callers type-assert and refuse when the capability is absent.
//
// sinceID is the dedup cursor: only entries with ID > sinceID are returned,
// so a poller and a webhook delivery of the same comment collapse on the same
// ID (the TaskEnvelope.IdempotencyKey pattern applied to reviews).
type PullRequestReviewReader interface { type PullRequestReviewReader interface {
ListReviews(ctx context.Context, owner, repo string, number int, sinceID int64) ([]Review, error) ListReviews(ctx context.Context, owner, repo string, number int, sinceID int64) ([]Review, error)
ListReviewComments(ctx context.Context, owner, repo string, number int, sinceID int64) ([]ReviewComment, error) ListReviewComments(ctx context.Context, owner, repo string, number int, sinceID int64) ([]ReviewComment, error)
@@ -189,34 +178,15 @@ type InlineReviewComment struct {
Body string Body string
} }
// ReviewCommentWriter posts line-anchored review comments on an open pull // ReviewCommentWriter posts line-anchored review comments on a PR, refusing
// request. Forge implementations that cannot (the noop forge) do not implement // when the head has moved past reviewedHeadSHA. Empty reviewedHeadSHA skips
// it; callers type-assert and degrade to the PR-body list rather than faking it. // the check.
//
// The set travels in one call because that is Gitea's native shape (a single
// COMMENT-state review carrying many comments); GitHub loops internally. Each
// implementation reads the pull request's current head itself and anchors the
// comments to it, but only after checking it against reviewedHeadSHA -- the
// revision the caller's line numbers were measured on. A line number that
// outlives its revision does not fail loudly at the forge: it attaches to
// whatever is on that line now, so the set is refused once the head has moved.
// An empty reviewedHeadSHA means the caller could not measure one, and posts
// unanchored by revision rather than dropping every finding.
type ReviewCommentWriter interface { type ReviewCommentWriter interface {
CreateReviewComments(ctx context.Context, owner, repo string, number int, reviewedHeadSHA string, comments []InlineReviewComment) error CreateReviewComments(ctx context.Context, owner, repo string, number int, reviewedHeadSHA string, comments []InlineReviewComment) error
} }
// reviewHeadDrift is the rule ReviewCommentWriter's implementations share: a // reviewHeadDrift returns an error when head is no longer reviewedHeadSHA.
// line-anchored comment set may be posted only while the pull request's head is // Empty reviewedHeadSHA returns nil.
// still the revision those line numbers were measured on. It returns nil when
// there is nothing to refuse, including when the caller could not measure a
// revision at all (reviewedHeadSHA == "") -- posting unverified is the
// pre-existing behaviour, and is strictly better than dropping every finding.
//
// The check lives here rather than in each implementation because the danger is
// identical on both: GitHub and Gitea accept a line number against the current
// head and anchor it to whatever now occupies that line, so a stale anchor does
// not fail loudly -- it misinforms.
func reviewHeadDrift(owner, repo string, number int, head, reviewedHeadSHA string) error { func reviewHeadDrift(owner, repo string, number int, head, reviewedHeadSHA string) error {
if reviewedHeadSHA == "" || strings.EqualFold(head, reviewedHeadSHA) { if reviewedHeadSHA == "" || strings.EqualFold(head, reviewedHeadSHA) {
return nil return nil
+2 -16
View File
@@ -268,22 +268,8 @@ func (c *GiteaClient) ReplyToReview(ctx context.Context, owner, repo string, num
return nil return nil
} }
// CreateReviewComments posts the line-anchored comments as one COMMENT-state // CreateReviewComments posts the comments as one COMMENT review on the PR's
// review, anchored to the pull request's head revision. // head, refused if the head moved past reviewedHeadSHA.
//
// Gitea has no standalone inline-comment call: inline comments are carried by a
// submitted review, so a single review is both the native shape and the fewest
// round trips. It is also all-or-nothing -- one comment Gitea refuses fails the
// whole request, and the review carries nothing -- where GitHub's loop keeps the
// comments it could post. The PR-body findings list is the fallback in either
// case.
//
// The head SHA is read here rather than taken from the caller: it is what Gitea
// anchors the review to, and the caller that produced the line numbers (a
// workflow stage running in archie-agent) holds no forge credentials to read it
// with. reviewedHeadSHA is the revision those line numbers were measured on, and
// the review is refused outright if the head has moved past it -- see
// reviewHeadDrift.
func (c *GiteaClient) CreateReviewComments(ctx context.Context, owner, repo string, number int, reviewedHeadSHA string, comments []InlineReviewComment) error { func (c *GiteaClient) CreateReviewComments(ctx context.Context, owner, repo string, number int, reviewedHeadSHA string, comments []InlineReviewComment) error {
pr, err := c.GetPullRequest(ctx, owner, repo, number) pr, err := c.GetPullRequest(ctx, owner, repo, number)
if err != nil { if err != nil {
+5 -25
View File
@@ -202,11 +202,8 @@ func (c *GitHubClient) GetPullRequestDiff(ctx context.Context, owner, repo strin
return diff, nil return diff, nil
} }
// GetRepoArchive fetches a gzipped tar archive of the repository at ref. // GetRepoArchive downloads a gzipped tar of the repository at ref. The
// GetArchiveLink only resolves the download's final location; the archive's // download URL is pre-signed, so no token is sent.
// bytes still have to be fetched with a plain, unauthenticated GET (the URL
// GitHub redirects to is a pre-signed storage link, not a GitHub API
// endpoint), so no forge token is attached to this second request.
func (c *GitHubClient) GetRepoArchive(ctx context.Context, owner, repo, ref string) (io.ReadCloser, error) { func (c *GitHubClient) GetRepoArchive(ctx context.Context, owner, repo, ref string) (io.ReadCloser, error) {
url, _, err := c.gh.Repositories.GetArchiveLink(ctx, owner, repo, github.Tarball, &github.RepositoryContentGetOptions{Ref: ref}, 5) url, _, err := c.gh.Repositories.GetArchiveLink(ctx, owner, repo, github.Tarball, &github.RepositoryContentGetOptions{Ref: ref}, 5)
if err != nil { if err != nil {
@@ -301,19 +298,9 @@ func (c *GitHubClient) ReplyToReview(ctx context.Context, owner, repo string, nu
return nil return nil
} }
// CreateReviewComments posts line-anchored review comments, one GitHub call per // CreateReviewComments posts each comment on the PR head's new side, refused
// comment, anchored to the RIGHT (new) side of the pull request's head revision. // if the head moved past reviewedHeadSHA. Failures are joined; the rest are
// // still posted.
// The head SHA is read here rather than taken from the caller: it is what the
// comments are anchored to, and the caller that produced the line numbers (a
// workflow stage running in archie-agent) holds no forge credentials to read it
// with. reviewedHeadSHA is the revision those line numbers were measured on, and
// the set is refused outright if the head has moved past it -- see
// reviewHeadDrift.
//
// A comment GitHub refuses -- a line that falls outside the diff, a file the
// push renamed -- does not abandon the rest. The failures are joined and
// returned, so one unanchorable finding cannot silently drop the others.
func (c *GitHubClient) CreateReviewComments(ctx context.Context, owner, repo string, number int, reviewedHeadSHA string, comments []InlineReviewComment) error { func (c *GitHubClient) CreateReviewComments(ctx context.Context, owner, repo string, number int, reviewedHeadSHA string, comments []InlineReviewComment) error {
head, err := c.reviewHeadSHA(ctx, owner, repo, number) head, err := c.reviewHeadSHA(ctx, owner, repo, number)
if err != nil { if err != nil {
@@ -370,13 +357,6 @@ func (c *GitHubClient) LinkBranch(ctx context.Context, owner, repo string, issue
return nil return nil
} }
// State labels mirror the task lifecycle onto the forge so archie's
// status is visible at a glance. SQLite remains the source of truth;
// labels are the human-facing projection -- and removing the parked
// label is the forge-native retry trigger.
// Label strings are configured via [dispatch.labels]; these are the
// built-in defaults used as a fallback when config is absent.
// stateLabelColors maps label name → colour for on-demand creation. // stateLabelColors maps label name → colour for on-demand creation.
var stateLabelColors = map[string]string{ var stateLabelColors = map[string]string{
"archie:queued": "bfd4f2", // grey-blue "archie:queued": "bfd4f2", // grey-blue
+6 -42
View File
@@ -1,33 +1,6 @@
// Package webhook implements the GitHub forge webhook receiver: an HTTP // Package webhook receives GitHub issue and review webhooks, verifies their
// endpoint that verifies a GitHub webhook's HMAC signature, decodes the // HMAC and publishes them through the poller's publish path. Only
// "issues" event, and publishes a matched issue as a workintake.TaskEnvelope. // application/json payloads are accepted. A GET returns delivery Status.
//
// It is forge intake, distinct from internal/channels/webhook (the chat
// channel): that package routes inbound text through the gateway for LLM
// processing; this one decodes a GitHub payload into the same TaskEnvelope
// the poller produces and hands it to the same publish path, so a labelled or
// assigned issue becomes work the moment it happens rather than up to
// poll_interval later.
//
// GitHub's webhook must be configured with "Content type: application/json"
// (the UI default). The alternate application/x-www-form-urlencoded delivery
// is not decoded here and is rejected as a bad payload.
//
// Idempotency is not this package's job: it decodes into the same TaskEnvelope
// and calls the same publish path the poller uses, so PublishUnique's dedup
// (keyed on TaskEnvelope.IdempotencyKey) covers both sources for free. What
// this package does own is making a wedged or non-delivering receiver
// observable: a GET to the listen address (GitHub only ever POSTs) returns
// Status, tracking authenticated deliveries and successful publishes separately
// so an operator can tell "receiver is up but nothing is arriving" apart from
// "repo has no issue activity."
//
// The GET/Status route is deliberately unauthenticated, on the same
// internet-facing listener GitHub POSTs signed payloads to: it reveals
// counters and timestamps only, never repo data, issue content, or the
// webhook secret, so treating it as a public liveness probe (the same
// tradeoff an unauthenticated /healthz makes) is an acceptable exchange for
// not requiring a second credential just to check if the receiver is alive.
package webhook package webhook
import ( import (
@@ -54,12 +27,7 @@ const maxBodyBytes = 1 << 20 // 1 MiB
// (*daemon.Daemon).PublishTask, the same enqueue path the poller uses. // (*daemon.Daemon).PublishTask, the same enqueue path the poller uses.
type PublishFunc func(ctx context.Context, task workintake.TaskEnvelope) error type PublishFunc func(ctx context.Context, task workintake.TaskEnvelope) error
// ReactionPublishFunc delivers one decoded review reaction to the reaction // ReactionPublishFunc publishes one review reaction.
// stream (pr-review-remediation.md decision 2's webhook producer). The
// composition root wires it to PublishUnique against the envelope's reaction
// subject, so a webhook delivery and a poll record of the same review dedup
// on the envelope's source-independent key. The reaction path carries no
// dispatch predicate: eligibility is the consumer's owned-PR lookup.
type ReactionPublishFunc func(ctx context.Context, reaction workintake.ReviewCommentEnvelope) error type ReactionPublishFunc func(ctx context.Context, reaction workintake.ReviewCommentEnvelope) error
// reactionRateLimit bounds reaction deliveries per remote source per window // reactionRateLimit bounds reaction deliveries per remote source per window
@@ -118,12 +86,8 @@ func New(secret, trigger, label, botUser string, publish PublishFunc, reactionPu
} }
} }
// Status reports the receiver's delivery activity so an operator can tell a // Status counts authenticated deliveries and published tasks.
// wedged or non-delivering receiver apart from a repo with no issue // LastReceivedAt is nil before the first delivery.
// activity: Deliveries counts every authenticated,
// parseable webhook -- proof GitHub reached this process at all -- while
// Publishes counts only what the dispatch predicate turned into work.
// LastReceivedAt is nil until the first authenticated delivery arrives.
type Status struct { type Status struct {
StartedAt time.Time `json:"started_at"` StartedAt time.Time `json:"started_at"`
LastReceivedAt *time.Time `json:"last_received_at"` LastReceivedAt *time.Time `json:"last_received_at"`
+8 -52
View File
@@ -1,25 +1,5 @@
// Package forgerpc lets archie-agent call the forge methods workflow stages // Package forgerpc lets archie-agent call the workflow.Forger methods over
// invoke mid-run -- CloseIssue, CreatePR, LinkBranch, CreateReviewComments, // NATS request/reply, so only archied holds forge credentials.
// Comment and ReplyToReview, the workflow.Forger set -- over core NATS
// request/reply, instead of the agent
// container holding a live forge API token. archied remains the sole holder of
// forge credentials and the sole caller of forge.Forge.
//
// The rest of forge.Forge (issue polling, invitations, reactions, PR-state
// reconciliation) is used exclusively by the daemon's own poll/reconcile
// loops, never from inside a workflow stage, so there is nothing for
// archie-agent to call.
//
// The server also still answers Comment and SetStateLabel. No current agent
// calls them; the handlers exist so an older archie-agent image keeps working
// against a newer daemon. The compatibility is one-directional: a NEW agent
// against an OLD daemon has no LinkBranch handler to reach, and the request
// times out, so an image skew that way parks tasks. Note it in release notes
// rather than assuming either side can lag.
//
// CreateReviewComments is the one method whose absence does NOT park a task: the
// stage that calls it is best-effort by design, so the same new-agent/old-daemon
// skew costs the inline comments and leaves the PR-body findings list intact.
package forgerpc package forgerpc
import ( import (
@@ -48,12 +28,8 @@ const (
SubjectReplyToReview = "archie.forge.reply_to_review" SubjectReplyToReview = "archie.forge.reply_to_review"
) )
// SubjectFor returns the subject for base, scoped to identity when set. // SubjectFor returns base scoped to identity, or base when identity is
// An empty identity uses the root subject, which is how single-identity // empty.
// deployments and agent images that predate identity routing behave. The
// daemon registers one server per identity on these scoped subjects so a
// container-mode task owned by a non-root identity has its RPC calls
// served by that identity's own forge client, not the root's.
func SubjectFor(identity, base string) string { func SubjectFor(identity, base string) string {
if identity == "" { if identity == "" {
return base return base
@@ -100,21 +76,11 @@ type SetStateLabelRequest struct {
KnownLabels []string KnownLabels []string
} }
// CreateReviewCommentsRequest carries one review's worth of line-anchored // CreateReviewCommentsRequest is one review's line-anchored comments.
// comments. The payload mirrors workflow.ReviewComment rather than reusing it:
// the wire shape is a contract between two processes that can be at different
// versions, so it is stated here instead of inherited from a type that may be
// renamed or reshaped for reasons that never crossed the wire.
type CreateReviewCommentsRequest struct { type CreateReviewCommentsRequest struct {
Owner, Repo string Owner, Repo string
Number int Number int
// ReviewedHeadSHA is the revision the comments' line numbers were measured // ReviewedHeadSHA is the revision the line numbers were measured on.
// on, which the worker records when it opens the pull request. It is
// additive on the wire: a worker that predates it omits the field and the
// server posts unverified (the pre-existing behaviour) rather than refusing
// every set, and a server that predates it ignores the field. Neither
// direction breaks, and neither silently mints a revision that was never
// measured.
ReviewedHeadSHA string ReviewedHeadSHA string
Comments []InlineReviewCommentPayload Comments []InlineReviewCommentPayload
} }
@@ -270,11 +236,6 @@ func (c *Client) rpc() *natsrpc.Client { return &natsrpc.Client{Conn: c.Conn, Ti
func (c *Client) subject(base string) string { return SubjectFor(c.Identity, base) } func (c *Client) subject(base string) string { return SubjectFor(c.Identity, base) }
// Comment and SetStateLabel are not in workflow.Forger, so no current agent
// calls them. They stay as the client half of handlers kept for image skew
// (see the package doc) -- and as the only way to exercise those handlers
// end to end, which is why removing them would leave the compatibility path
// untested rather than merely unused.
func (c *Client) Comment(ctx context.Context, owner, repo string, number int, body string) (int64, error) { func (c *Client) Comment(ctx context.Context, owner, repo string, number int, body string) (int64, error) {
req := CommentRequest{Owner: owner, Repo: repo, Number: number, Body: body} req := CommentRequest{Owner: owner, Repo: repo, Number: number, Body: body}
resp, err := natsrpc.Call[CommentResponse](ctx, c.rpc(), c.subject(SubjectComment), req) resp, err := natsrpc.Call[CommentResponse](ctx, c.rpc(), c.subject(SubjectComment), req)
@@ -324,13 +285,8 @@ func (c *Client) SetStateLabel(ctx context.Context, owner, repo string, number i
_, _ = natsrpc.Call[Response](ctx, c.rpc(), c.subject(SubjectSetStateLabel), req) _, _ = natsrpc.Call[Response](ctx, c.rpc(), c.subject(SubjectSetStateLabel), req)
} }
// CreateReviewComments posts the review's line-anchored findings on the pull // CreateReviewComments posts line-anchored comments on the PR through the
// request. It is the one proxied method a workflow stage treats as best-effort, // daemon.
// which is why it is also the one whose failure cannot park a task.
//
// reviewedHeadSHA travels with the call so the daemon -- the only side holding
// forge credentials, and so the only side that can read a pull request's head --
// can refuse a set whose line numbers describe a revision the PR has left.
func (c *Client) CreateReviewComments(ctx context.Context, owner, repo string, number int, reviewedHeadSHA string, comments []workflow.ReviewComment) error { func (c *Client) CreateReviewComments(ctx context.Context, owner, repo string, number int, reviewedHeadSHA string, comments []workflow.ReviewComment) error {
payload := make([]InlineReviewCommentPayload, 0, len(comments)) payload := make([]InlineReviewCommentPayload, 0, len(comments))
for _, cm := range comments { for _, cm := range comments {
+7 -22
View File
@@ -1,14 +1,6 @@
// Package access implements internal/domain/access's Authorizer with // Package access implements the Authorizer with cedar-go. Levels are
// github.com/cedar-policy/cedar-go. The engine owns policy parsing and // evaluated instance, org, workspace, object: a level with policies must
// validation against the shipped Cedar schema, and the chain evaluation: // permit and any forbid wins. Cross-org access is always denied.
// instance ▶ org ▶ workspace ▶ object, where a level with policies must
// permit, a forbid at any level wins, and with no permit the request is
// denied.
//
// The cross-org forbid is enforced here, structurally, before any Cedar
// runs: a principal never reaches a resource outside its org. It is not a
// stored policy, so it cannot be edited away or removed by
// `archied access reset`.
package access package access
import ( import (
@@ -24,12 +16,7 @@ import (
"github.com/samcharles93/archie-core/internal/domain/org" "github.com/samcharles93/archie-core/internal/domain/org"
) )
// schemaText is the Cedar schema the engine validates every policy against. // schemaText is the Cedar schema policies are validated against.
// It names the entity vocabulary internal/domain/access defines: an
// Identity principal carrying its org and effective role, the org and
// workspace parents, one Object entity per record, and one Action per
// action. Context carries the event's signature result, the address it came
// from, and the run and step of an agent's request.
const schemaText = `namespace Archie { const schemaText = `namespace Archie {
entity Identity in [Org] = {"org": String, "role": String}; entity Identity in [Org] = {"org": String, "role": String};
entity Org; entity Org;
@@ -98,11 +85,9 @@ var (
_ access.Validator = (*Engine)(nil) _ access.Validator = (*Engine)(nil)
) )
// New builds an engine over one snapshot of the stored policies. An invalid // New builds an engine from the stored policies. An invalid instance policy
// instance policy is a boot failure: it returns (nil, err) and archie stops // is an error; an invalid policy at another level makes that level deny
// serving until the policy is fixed. An invalid org, workspace or object // everything.
// policy becomes a Problem and makes its level deny everything -- the other
// levels still serve, and the health surface reports the problem by name.
func New(policies []access.Policy) (*Engine, error) { func New(policies []access.Policy) (*Engine, error) {
e := &Engine{ e := &Engine{
orgs: map[org.OrgID]*levelSet{}, orgs: map[org.OrgID]*levelSet{},
+3 -10
View File
@@ -12,11 +12,8 @@ import (
"github.com/samcharles93/archie-core/internal/domain/access" "github.com/samcharles93/archie-core/internal/domain/access"
) )
// buildRequest turns the assembled request into the engine's shape. The // buildRequest converts a request for Cedar, including only the context
// context record carries only the fields that were set: a policy testing a // fields that were set.
// field the caller did not supply cannot match, which is the fail-closed
// reading of "context: the event's signature result, the address it came
// from, the time, and the run and step when the principal is an agent".
func buildRequest(p access.Principal, a access.Action, r access.Resource, c access.Context) types.Request { func buildRequest(p access.Principal, a access.Action, r access.Resource, c access.Context) types.Request {
record := types.RecordMap{} record := types.RecordMap{}
if c.Signature != "" { if c.Signature != "" {
@@ -48,11 +45,7 @@ func buildRequest(p access.Principal, a access.Action, r access.Resource, c acce
} }
} }
// buildEntities assembles the entity graph policies may walk: the principal // buildEntities builds the principal, resource and parent entities.
// (its org and effective role), the resource (its kind, org, workspace,
// owner and state), and the org and workspace parents the resource hangs
// from. A policy naming a parent the request does not supply simply does
// not match.
func buildEntities(p access.Principal, r access.Resource) cedar.EntityMap { func buildEntities(p access.Principal, r access.Resource) cedar.EntityMap {
resOrg := r.Org resOrg := r.Org
if resOrg == "" { if resOrg == "" {
+2 -23
View File
@@ -22,29 +22,8 @@ func MarkSafe(ctx context.Context, mountDir string, log *slog.Logger) bool {
return markSafe(ctx, mountDir, runGit, log) return markSafe(ctx, mountDir, runGit, log)
} }
// markSafe adds mountDir to git's global safe.directory list. // markSafe adds mountDir to git's global safe.directory when it is an
// // existing directory. Failures are logged. Returns true on success.
// The daemon bind-mounts the task worktree into the container from the host,
// so the directory is owned by a UID the container user is not. Git refuses to
// operate in a repository it does not own ("detected dubious ownership"), and
// the Go toolchain shells out to git for VCS stamping during build/test/vet --
// so without this every gate fails before the agent does any real work.
//
// Best-effort by design: git may be absent from a minimal image, and an agent
// working a repo with no gate commands never needs it. A failure is logged and
// the agent continues. Returns true only when git accepted the configuration.
//
// The guard is existence, not mount-ness: os.Stat confirms mountDir exists and
// is a directory, which prevents a misconfigured archie-agent from writing to
// the operator's own ~/.gitconfig for a workspace path that was never mounted.
// Mandatory task boot metadata independently rejects non-task workers before
// they subscribe. This check does not detect a
// stale directory that happens to exist at the same path without actually
// being a bind mount -- a real mount check would need platform-specific
// parsing (e.g. /proc/self/mountinfo on Linux) that this deliberately does
// without. The failure mode is inert: git only rejects operations in a
// directory that both exists at this path and is a real repository, and
// safe.directory entries for a stale non-repo path do nothing.
func markSafe(ctx context.Context, mountDir string, run gitRunner, log *slog.Logger) bool { func markSafe(ctx context.Context, mountDir string, run gitRunner, log *slog.Logger) bool {
info, err := os.Stat(mountDir) info, err := os.Stat(mountDir)
if err != nil || !info.IsDir() { if err != nil || !info.IsDir() {
@@ -48,11 +48,7 @@ type sdkSubscription interface {
// worker has no JetStream consumer. // worker has no JetStream consumer.
type Transport struct { type Transport struct {
conn *natsio.Conn conn *natsio.Conn
// state is the long-lived State Store contract client and closeState its // state is the State Store client; closeState closes its connection.
// connection cleanup. Store() dials nothing per call; it wraps this one
// client with the per-call timeout each caller supplies. Connect refuses
// to construct a Transport without one (the legacy NATS storerpc path is
// deleted), so it is never nil in a real worker.
state *staterpc.Client state *staterpc.Client
closeState func() closeState func()
@@ -60,11 +56,7 @@ type Transport struct {
flush func(time.Duration) error flush func(time.Duration) error
} }
// Connect establishes the worker's core-NATS connection and, when // Connect opens the worker's NATS connection and its State Store connection.
// Config.StateStoreURL is set, a long-lived gRPC connection to the State
// Store. A non-loopback
// StateStoreURL with no token fails closed rather than dialing an
// unauthenticated remote store.
func Connect(ctx context.Context, config Config, log *slog.Logger) (*Transport, error) { func Connect(ctx context.Context, config Config, log *slog.Logger) (*Transport, error) {
if log == nil { if log == nil {
log = slog.New(slog.DiscardHandler) log = slog.New(slog.DiscardHandler)
@@ -132,23 +124,13 @@ type RemoteTrees interface {
Push(ctx context.Context) error Push(ctx context.Context) error
} }
// The top-level forgerpc and worktreerpc packages remain legacy infrastructure
// with an open final destination. This adapter is their single worker
// composition point until that broader migration is approved. The State Store
// is the exception: it is a gRPC contract (staterpc), and this adapter's
// Store() returns that client directly.
// Forger constructs the identity-scoped forge RPC client. // Forger constructs the identity-scoped forge RPC client.
func (t *Transport) Forger(identity string, timeout time.Duration) workflow.Forger { func (t *Transport) Forger(identity string, timeout time.Duration) workflow.Forger {
return &forgerpc.Client{Conn: t.conn, Timeout: timeout, Identity: identity} return &forgerpc.Client{Conn: t.conn, Timeout: timeout, Identity: identity}
} }
// Store constructs the workflow store RPC client over the long-lived State // Store returns the State Store client, bounding each call by timeout when
// Store client. Each call is bounded // ctx has no deadline.
// by timeout when the caller's context carries no deadline of its own. The
// legacy NATS storerpc path is deleted; a transport without a
// State Store client cannot reach Store() because Connect refused to build
// one.
func (t *Transport) Store(timeout time.Duration) workflow.Store { func (t *Transport) Store(timeout time.Duration) workflow.Store {
return deadlineStore{Store: t.state, timeout: timeout} return deadlineStore{Store: t.state, timeout: timeout}
} }
@@ -33,11 +33,7 @@ type Domain struct {
} }
var ( var (
// BindingDomain seals binding.Binding.Secret and source webhook // BindingDomain seals binding and source webhook secrets. Not row-bound.
// secrets -- the original domain this package was built for. It is
// deliberately NOT row-bound: these are random HMAC keys, never used
// as lookup keys, so cross-row relocation within the domain is not a
// meaningful attack.
BindingDomain = Domain{marker: "arcie-binding", aad: []byte("arcie-binding-secret")} BindingDomain = Domain{marker: "arcie-binding", aad: []byte("arcie-binding-secret")}
// HarnessSecretDomain seals harness OAuth token sets // HarnessSecretDomain seals harness OAuth token sets
// -- its own // -- its own
@@ -69,22 +65,16 @@ type BindingCipher interface {
DecryptDomain(d Domain, envelope string) (string, error) DecryptDomain(d Domain, envelope string) (string, error)
} }
// bindingCipher is the AES-256-GCM BindingCipher. Keys are derived as // bindingCipher is AES-256-GCM with keys SHA-256(material). The active key
// SHA-256(resolved material) -- 32 bytes of high-entropy input re-shaped to a // seals; previous keys only decrypt.
// 256-bit key, so no passphrase-stretching KDF (Argon2id) is required. The
// active key seals new writes; previous keys are retained for decryption only
// during rotation.
type bindingCipher struct { type bindingCipher struct {
activeKey []byte activeKey []byte
activeFingerprint string activeFingerprint string
keys map[string][]byte // fingerprint(hex[:16]) → 32-byte AES key keys map[string][]byte // fingerprint(hex[:16]) → 32-byte AES key
} }
// NewBindingCipher builds a bindingCipher over the active key material and any // NewBindingCipher builds a cipher over the active and previous key
// previous (decrypt-only) material. Key identity is intrinsic to the material // material. Keys are identified by fingerprint.
// (the SHA-256 fingerprint), so rotation needs no manual key IDs. It is a pure
// constructor: it never reads the secret registry, which the composition root
// owns.
func NewBindingCipher(active string, previous []string) (*bindingCipher, error) { func NewBindingCipher(active string, previous []string) (*bindingCipher, error) {
if active == "" { if active == "" {
return nil, errors.New("store: binding cipher requires a non-empty active key") return nil, errors.New("store: binding cipher requires a non-empty active key")
@@ -138,11 +128,8 @@ func (c *bindingCipher) EncryptDomain(d Domain, plaintext string) (string, error
c.activeFingerprint, base64.RawURLEncoding.EncodeToString(payload)), nil c.activeFingerprint, base64.RawURLEncoding.EncodeToString(payload)), nil
} }
// DecryptDomain parses an envelope sealed under d, looks up the key by its // DecryptDomain decrypts an envelope sealed under d. An unknown key or wrong
// embedded fingerprint, and returns the plaintext. A fingerprint not present // domain is an error.
// in the keyring (an old key dropped from config), or an envelope sealed
// under a different domain's marker/AAD, fails rather than returning
// garbage.
func (c *bindingCipher) DecryptDomain(d Domain, envelope string) (string, error) { func (c *bindingCipher) DecryptDomain(d Domain, envelope string) (string, error) {
parts := strings.SplitN(envelope, ":", 4) parts := strings.SplitN(envelope, ":", 4)
if len(parts) != 4 || parts[0] != d.marker || parts[1] != bindingEnvelopeVersion { if len(parts) != 4 || parts[0] != d.marker || parts[1] != bindingEnvelopeVersion {
@@ -1,15 +1,5 @@
// Package captureintake is the HTTP receiver for inbound webhooks archie has // Package captureintake receives and stores inbound webhooks for inspection
// no binding for yet: it persists what arrives so an operator can inspect it // and binding dispatch.
// and build one.
//
// It belongs to the process that owns work intake, not to the dashboard that
// displays captures. It served from the dashboard's listener while the two
// shared a process; the split gives the read to the dashboard, over the State
// Store, and keeps the write here. From the cutover
// change in the same bead it is a persistence shim over the State Store
// contract mounted by the UI process -- the only dashboard listener left --
// while the daemon's binding-dispatch loop consumes captures from the same
// store: the HTTP front door moved without moving work intake.
package captureintake package captureintake
import ( import (
@@ -70,12 +60,9 @@ func (rc *Receiver) Register(mux *http.ServeMux) {
mux.HandleFunc(Path, rc.ServeHTTP) mux.HandleFunc(Path, rc.ServeHTTP)
} }
// ServeHTTP accepts an inbound webhook POST and persists it. On a signed // ServeHTTP stores an inbound webhook. A valid HMAC on a signed source marks
// source only a valid HMAC under the source's secret marks the event // it authenticated; an approved unsigned source marks it unsigned; other
// authenticated; on an approved unsigned source every event is marked // events are stored but never dispatch.
// unsigned. Anything else is still captured and visible in the inspector,
// but is neither, so the dispatch loop's check (binding.Matcher.Matches over
// CapturedEvent.Dispatchable) never starts a task from it.
func (rc *Receiver) ServeHTTP(w http.ResponseWriter, r *http.Request) { func (rc *Receiver) ServeHTTP(w http.ResponseWriter, r *http.Request) {
if rc.Captures == nil { if rc.Captures == nil {
http.Error(w, "capture not configured", http.StatusServiceUnavailable) http.Error(w, "capture not configured", http.StatusServiceUnavailable)
@@ -83,14 +70,7 @@ func (rc *Receiver) ServeHTTP(w http.ResponseWriter, r *http.Request) {
} }
path := r.PathValue("source") path := r.PathValue("source")
// webhookguard.RateLimiter's bucket map assumes a bounded, operator- // Rate limit by remote address; the source segment is attacker-chosen.
// registered key space (see its doc comment) -- it is never evicted, and
// a fresh key starts with a full burst allowance. source is an
// unregistered, attacker-chosen URL segment by design (this endpoint
// exists to capture senders archie has no registration for yet), so
// keying on it would let a single attacker rotate a new "source" on
// every request to bypass the limit entirely and grow the bucket map
// without bound. Remote address is the bounded identity available here.
if rc.Limiter != nil && !rc.Limiter.Allow(remoteAddrHost(r)) { if rc.Limiter != nil && !rc.Limiter.Allow(remoteAddrHost(r)) {
http.Error(w, "rate limit exceeded", http.StatusTooManyRequests) http.Error(w, "rate limit exceeded", http.StatusTooManyRequests)
return return
@@ -169,11 +149,9 @@ func (rc *Receiver) resolveSource(r *http.Request, path string) *source.Source {
return src return src
} }
// verify decides how an event on src may dispatch. An approved unsigned // verify reports how an event on src may dispatch: unsigned for an approved
// source marks it unsigned. Otherwise a valid HMAC under the source's secret // unsigned source, else authenticated by a valid X-Hub-Signature-256 or
// authenticates it: X-Hub-Signature-256 first, X-Signature-256 as fallback. // X-Signature-256. A source with no secret authenticates nothing.
// A source with no secret yet authenticates nothing, since an empty key is
// one anybody can sign with.
func verify(src *source.Source, h http.Header, body []byte) (authenticated, unsigned bool) { func verify(src *source.Source, h http.Header, body []byte) (authenticated, unsigned bool) {
switch { switch {
case src == nil: case src == nil:
@@ -1,33 +1,7 @@
// Package tomlwrite patches specific keys in a TOML document without // Package tomlwrite edits keys in a TOML document as text, leaving comments,
// disturbing anything else in it -- including comments, blank lines, and // blank lines and order untouched. Apply replaces an active key, uncomments
// key order. // a commented one, or appends it to its table. Only single-line values are
// // supported.
// # Why not decode/re-marshal
//
// BurntSushi/toml does not round-trip comments: a Decode followed by an Encode
// reproduces the data but discards every comment. config.example.toml carries
// substantial documentation as inline comments that operators are meant to read
// and hand-edit, and archied setup must be able to write into that same file --
// and be re-run later to change one value -- without deleting it. A full
// re-marshal was rejected for that reason.
//
// # The chosen strategy
//
// Apply treats the document as text and edits only the lines a caller
// names. For each requested key it looks, in order, for: an active
// "key = value" line in the target table (replace the value, keep any
// trailing inline comment); a commented-out "# key = value" line in the
// target table (uncomment the table header and the line, then replace the
// value); or, failing both, a place to add the key (the end of the
// table's existing content, or a brand new table appended at the end of
// the document). Every line Apply was not asked to touch is copied through
// unchanged, byte for byte.
//
// It only understands single-line scalar and inline-table values (strings,
// numbers, booleans, `{ engine = "...", key = "..." }` secret refs), which
// covers everything archied setup writes. Multi-line arrays and
// [[array-of-tables]] entries are not targets for Apply; other code paths (e.g.
// adding a [[repos]] entry) must not use it.
package tomlwrite package tomlwrite
import ( import (
@@ -38,13 +12,8 @@ import (
"strings" "strings"
) )
// Edit is one key = value change to make within a TOML document. // Edit sets one key in a TOML table. Table is a dotted path ("" for the
// // root). Value is a literal TOML value; see String and Ref.
// Table is the dotted path to the table the key lives in ("" for the
// document root, "forge", "providers.openai", "chat.telegram", ...). Value
// is the exact TOML literal to write -- callers are responsible for
// quoting it themselves; see [String] and [Ref] for the two shapes archied
// setup needs.
type Edit struct { type Edit struct {
Table string Table string
Key string Key string
@@ -71,11 +40,7 @@ var (
commentedKeyRe = regexp.MustCompile(`^(\s*)#\s?([A-Za-z0-9_.]+)(\s*=\s*)(.*)$`) commentedKeyRe = regexp.MustCompile(`^(\s*)#\s?([A-Za-z0-9_.]+)(\s*=\s*)(.*)$`)
) )
// Generate applies edits to template and returns the result: a config a // Generate applies edits to template.
// human can read and hand-edit afterwards, since it is the documented
// template with only the requested values filled in. archied setup calls
// this on first run, with configtemplate.Example as template, and calls
// Apply directly against the existing file on every later run.
func Generate(template []byte, edits []Edit) ([]byte, error) { func Generate(template []byte, edits []Edit) ([]byte, error) {
return Apply(template, edits) return Apply(template, edits)
} }
@@ -1,8 +1,5 @@
// Package controlplanerpc is the Messaging Service side of the control-plane // Package controlplanerpc is the control-plane resource client and the
// contract: the generic resource client, the channel-settings document it // channel-settings document.
// projects, and the wire sentinels both sides match on. It exists so a service
// that only reads stored settings does not link the store-backed server, the
// workflow engine or the SQLite driver.
package controlplanerpc package controlplanerpc
import ( import (
@@ -45,13 +42,6 @@ func NewClient(conn grpc.ClientConnInterface) *Client {
func NewRPCClient(client pb.ControlPlaneServiceClient) *Client { return &Client{rpc: client} } func NewRPCClient(client pb.ControlPlaneServiceClient) *Client { return &Client{rpc: client} }
// WorkflowDefinitionsClient reads and replaces the workflow-definitions
// resource, the one control-plane surface whose stored values name workflow
// step types. Resolving those names needs the step vocabulary the process
// registered at its composition root, so the vocabulary is a constructor
// dependency of this surface and of no other: a caller that cannot reach
// workflow definitions cannot ask for one.
// ResourceReader is the read side of the control-plane client: one resource // ResourceReader is the read side of the control-plane client: one resource
// query per kind. The store-backed server implements it too, which is why the // query per kind. The store-backed server implements it too, which is why the
// layering functions here are shared with internal/app/controlplane. // layering functions here are shared with internal/app/controlplane.
@@ -110,15 +100,6 @@ func RuntimeChatConfigFrom(ctx context.Context, reader ResourceReader, base conf
return out, version, nil return out, version, nil
} }
// layerResource decodes a resource and records the version it came from, so the
// layering ends up holding the version of every kind it applied.
//
// A kind with no stored value is not an error and records no version: the file
// document's value stays in effect. That is the state a seed the resource
// validator refused leaves behind (controlplane.Server.ImportConfig skips it),
// and failing here instead would stop the process with a database-named error
// that editing config.toml cannot clear.
// ClientError maps a gRPC status onto the wire sentinels both sides match on. // ClientError maps a gRPC status onto the wire sentinels both sides match on.
// It is exported because the store-backed server's own client methods need the // It is exported because the store-backed server's own client methods need the
// same mapping, and a second copy would be a second contract. // same mapping, and a second copy would be a second contract.
@@ -7,12 +7,8 @@ import (
"github.com/samcharles93/archie-core/internal/domain/org" "github.com/samcharles93/archie-core/internal/domain/org"
) )
// Every control-plane request acts in one org's copy of a resource. The org // Requests carry the org from the context (org.WithOrg), defaulting to the
// travels on the request context (org.WithOrg), attached once by whatever // default org.
// established the caller's principal, and these constructors are the one place
// it is read back: a call site cannot send the wrong org, and a new call site
// cannot forget it. org.OrgFromContext yields the default org when the context
// carries none, so a process with no principal still acts where it always did.
// QueryRequest builds a resource query for the caller's org. // QueryRequest builds a resource query for the caller's org.
func QueryRequest(ctx context.Context, kind string) *pb.QueryRequest { func QueryRequest(ctx context.Context, kind string) *pb.QueryRequest {
@@ -9,13 +9,8 @@ import (
"github.com/samcharles93/archie-core/internal/config" "github.com/samcharles93/archie-core/internal/config"
) )
// ChannelSettings is the Channel settings resource document. Its shape IS the // ChannelSettings is the channel-settings resource document, with
// contract the Web UI edits, so every nested object here is defined by this // snake_case JSON keys.
// file with explicit snake_case json tags and never handed an internal config
// struct. Encoding/json falls back to Go field names when a tag is absent,
// which is how "Window", "MaxRequests", "ListenAddr" and "RelayAddr" reached
// operators in the first place -- a shape belonging to TOML, not to this
// document.
type ChannelSettings struct { type ChannelSettings struct {
Operator string `json:"operator"` Operator string `json:"operator"`
ShowToolCalls bool `json:"show_tool_calls"` ShowToolCalls bool `json:"show_tool_calls"`
@@ -88,11 +83,8 @@ func (r *RateLimitSettings) UnmarshalJSON(data []byte) error {
return nil return nil
} }
// DecodeRenamingLegacyKeys decodes an object into v after renaming each key in // DecodeRenamingLegacyKeys decodes data into v after renaming legacy keys.
// legacy to the spelling v documents, and stays strict about everything else. // Unknown keys are errors.
// The strictness is the point: dropping unknown keys would let a typo
// ("windows") read as "unset" and silently disable the setting, which is the
// class of failure this shape exists to end.
func DecodeRenamingLegacyKeys(data []byte, legacy map[string]string, v any) error { func DecodeRenamingLegacyKeys(data []byte, legacy map[string]string, v any) error {
var raw map[string]json.RawMessage var raw map[string]json.RawMessage
if err := json.Unmarshal(data, &raw); err != nil { if err := json.Unmarshal(data, &raw); err != nil {
@@ -117,11 +109,8 @@ func DecodeRenamingLegacyKeys(data []byte, legacy map[string]string, v any) erro
return decoder.Decode(v) return decoder.Decode(v)
} }
// ChannelDuration is a duration as this document writes it: the human string // ChannelDuration is written as a duration string; it also reads a
// the file accepts ("1m0s", the same spelling config.Duration emits), never a // nanosecond count.
// nanosecond count. It still reads the count, because every document written
// before this shape existed carries one, and reading both forms is what lets
// those documents keep working without being re-saved.
type ChannelDuration time.Duration type ChannelDuration time.Duration
// Std is the standard-library duration, for arithmetic and for the marker // Std is the standard-library duration, for arithmetic and for the marker
@@ -1,25 +1,5 @@
// Package crondelivery is the delivery half of archied's cron/scheduling // Package crondelivery delivers due scheduled jobs: ChatCourier sends a chat
// capability: it turns a due job into an effect. // message, WorkflowTask submits work, and Router picks one per job kind.
//
// The domain's ticker engine (internal/domain/scheduling) decides *when* a job
// runs and hands over a scheduling.Job — identity and dispatch policy, nothing
// more. This package owns what happens next, and it is the only place that
// knows a job store exists. The engine sees one Runner (the Router); the
// deliveries it dispatches to are a mapping this package holds.
//
// Three surfaces:
//
// - ChatCourier sends a job's payload text to a chat.
// - WorkflowTask submits a job as a unit of work.
// - Router picks between them per job kind, and is the single Runner the
// engine is given.
//
// No implementation here talks to a channel, a broker or a forge. Each takes
// the effect it needs as an injected function or narrow interface, so which
// chat transport carries a message — and which intake path receives a task —
// stays the deployment's decision (the wiring slice composes the real ones),
// not the cron's. That is also what keeps this package testable without a
// network.
package crondelivery package crondelivery
import ( import (
@@ -31,29 +11,14 @@ import (
"github.com/samcharles93/archie-core/internal/domain/scheduling" "github.com/samcharles93/archie-core/internal/domain/scheduling"
) )
// SpecLookup resolves a job id to its persisted spec. // SpecLookup resolves a job id to its stored spec.
//
// It is declared here (consumer-owned) rather than imported from the document's
// owner as a concrete type so this package depends on the one method it uses.
// scheduleResourceStore in internal/app/archied satisfies it as written, so a
// deployment passes that in.
type SpecLookup interface { type SpecLookup interface {
// Get returns the job and whether it was found; the error is reserved // Get returns the job and whether it was found; the error is reserved
// for I/O failures, matching scheduleResourceStore.Get. // for I/O failures, matching scheduleResourceStore.Get.
Get(ctx context.Context, id string) (scheduling.JobSpec, bool, error) Get(ctx context.Context, id string) (scheduling.JobSpec, bool, error)
} }
// RunRecorder advances a job's schedule once a run has completed. It is // RunRecorder advances a job's schedule after a successful run.
// declared here (consumer-owned) for the same reason SpecLookup is, and
// scheduleResourceStore satisfies it as written.
//
// MarkRun is the only step that moves a job's NextRun, so a store whose Due
// keeps reporting an already-completed job keeps handing it back on every
// tick: an interval job fires once per tick instead of once per interval. The
// record is written only for a successful run, matching the store's own
// contract that an interval or cron schedule fires "after the last successful
// run" -- a failed run retries at the tick rate rather than silently skipping
// its slot.
type RunRecorder interface { type RunRecorder interface {
// MarkRun records that id ran at runAt and advances NextRun to the // MarkRun records that id ran at runAt and advances NextRun to the
// schedule's next firing. // schedule's next firing.
@@ -69,23 +34,10 @@ type RouterStore interface {
RunRecorder RunRecorder
} }
// Courier sends one chat message. It is the whole outbound surface this // Courier sends one chat message. It must honour ctx.
// package needs, and it is injected: the concrete channel client lives in the
// deployment, so an operator switching transports changes nothing here. That
// is how "the channel choice stays the operator's, not the cron's" is enforced
// — by construction, there is no channel to choose from here.
//
// An implementation must honour ctx: the engine bounds every run with a
// timeout and cancels on shutdown, and a courier that blocks through
// cancellation keeps the run in flight past the engine's own deadline.
type Courier func(ctx context.Context, chatID, text string) error type Courier func(ctx context.Context, chatID, text string) error
// TaskSubmitter submits one unit of work to the work-intake path. // TaskSubmitter submits one unit of work.
//
// identity is the submitting job's id; title and body are the job's detail and
// payload. It is narrow on purpose: the concrete publisher builds the
// work-intake envelope, because the envelope carries owner/repo/number fields
// only the deployment can know. This package carries no forge vocabulary.
type TaskSubmitter interface { type TaskSubmitter interface {
Submit(ctx context.Context, identity, title, body string) error Submit(ctx context.Context, identity, title, body string) error
} }
+9 -35
View File
@@ -11,39 +11,21 @@ import (
"github.com/samcharles93/archie-core/internal/events" "github.com/samcharles93/archie-core/internal/events"
) )
// phaseDispatch names the step that failed on a KindJobError the Router emits. // phaseDispatch is the phase reported for a dispatch refusal; it matches the
// // scheduling engine's value.
// It is restated as a literal rather than referenced, because the engine's
// equivalent constant is unexported (internal/domain/scheduling's
// phaseDispatch). "dispatch" is a wire value on the event stream and this
// package must match it, so it is pinned here by value.
const phaseDispatch = "dispatch" const phaseDispatch = "dispatch"
// Router is the single Runner the engine is given. It resolves a due job's // Router runs a due job with the runner for its kind and records successful
// kind from its persisted spec and hands the job to that kind's runner, // runs. An unknown kind is reported as a dispatch KindJobError and Run
// keeping the engine unaware that more than one delivery exists. Once a run // returns nil.
// has succeeded it also records the run, which is what moves a recurring job's
// NextRun.
//
// An unknown kind is refused, not failed. It is reported on the event stream
// as KindJobError with phase "dispatch" — naming the gate, so an operator can
// distinguish a misconfigured job from a broken one — and Run returns nil.
// Returning an error instead would have the engine emit it as a failed *run*
// (phase "run"), conflating the two, and would leave the job looking like it
// tried and broke on every tick.
type Router struct { type Router struct {
specs RouterStore specs RouterStore
runners map[string]scheduling.Runner runners map[string]scheduling.Runner
sink scheduling.Sink sink scheduling.Sink
} }
// NewRouter builds the router over a spec lookup, its kind-to-runner mapping, // NewRouter builds a router over specs and runners. A nil sink disables
// and the sink its dispatch refusals are reported on. A nil sink disables // events. An empty kind is KindChat.
// emission — the router still refuses, it is just unobservable, the same
// tolerance the engine has for its own nil sink.
//
// An empty kind resolves to scheduling.KindChat, so a deployment only needs a
// mapping for the kinds it actually uses.
func NewRouter(specs RouterStore, runners map[string]scheduling.Runner, sink scheduling.Sink) (*Router, error) { func NewRouter(specs RouterStore, runners map[string]scheduling.Runner, sink scheduling.Sink) (*Router, error) {
if specs == nil { if specs == nil {
return nil, errors.New("crondelivery: spec lookup must not be nil") return nil, errors.New("crondelivery: spec lookup must not be nil")
@@ -79,16 +61,8 @@ func (r *Router) Run(ctx context.Context, job scheduling.Job) error {
return r.recordRun(ctx, job) return r.recordRun(ctx, job)
} }
// recordRun advances the job's schedule after a successful run. Without it the // recordRun advances the job's schedule after a successful run.
// store has no record that the job ran, so its NextRun stays in the past and // ErrScheduleUnsupported (a one-shot) is ignored.
// Due reports the job again on every tick: a job scheduled hourly fires once
// per tick instead.
//
// A schedule kind with no recurring next run -- a one-shot -- reports
// scheduling.ErrScheduleUnsupported, which is the job's definition rather than a
// run failure, so it is swallowed. Anything else is returned: the run happened
// but the bookkeeping did not, and hiding that would leave the job silently
// re-firing.
func (r *Router) recordRun(ctx context.Context, job scheduling.Job) error { func (r *Router) recordRun(ctx context.Context, job scheduling.Job) error {
if err := r.specs.MarkRun(ctx, job.ID, time.Now()); err != nil && !errors.Is(err, scheduling.ErrScheduleUnsupported) { if err := r.specs.MarkRun(ctx, job.ID, time.Now()); err != nil && !errors.Is(err, scheduling.ErrScheduleUnsupported) {
return fmt.Errorf("crondelivery: record run of job %q: %w", job.ID, err) return fmt.Errorf("crondelivery: record run of job %q: %w", job.ID, err)
+2 -11
View File
@@ -29,12 +29,7 @@ func NewChatCourier(specs SpecLookup, courier Courier) (*ChatCourier, error) {
return &ChatCourier{specs: specs, courier: courier}, nil return &ChatCourier{specs: specs, courier: courier}, nil
} }
// Run hydrates the job's spec and sends its payload text to its target chat. // Run sends the job's payload to its chat. A cancelled ctx sends nothing.
//
// The pre-check matters as much as the error wrap: a cancelled run must produce
// no side effect, because the engine cancels on shutdown and a message sent
// after that is one nobody asked for. The courier's own ctx handling covers
// cancellation that arrives mid-send.
func (c *ChatCourier) Run(ctx context.Context, job scheduling.Job) error { func (c *ChatCourier) Run(ctx context.Context, job scheduling.Job) error {
if err := ctx.Err(); err != nil { if err := ctx.Err(); err != nil {
return err return err
@@ -69,11 +64,7 @@ func NewWorkflowTask(specs SpecLookup, submitter TaskSubmitter) (*WorkflowTask,
return &WorkflowTask{specs: specs, submitter: submitter}, nil return &WorkflowTask{specs: specs, submitter: submitter}, nil
} }
// Run hydrates the job's spec and submits it as work. // Run submits the job as work, titled by Detail or the job id.
//
// The title falls back to the job id when Detail is empty: a submitted task is
// how a human finds the job that created it, and an untitled one is
// unfindable.
func (w *WorkflowTask) Run(ctx context.Context, job scheduling.Job) error { func (w *WorkflowTask) Run(ctx context.Context, job scheduling.Job) error {
if err := ctx.Err(); err != nil { if err := ctx.Err(); err != nil {
return err return err
+6 -20
View File
@@ -1,10 +1,5 @@
// Package drain is the infrastructure implementation of drain-request // Package drain reads the drain marker file and the current epoch and asks
// detection. It reads the external marker file from disk and the OS identity // domain drain.Decide for a verdict.
// facts that make up the current instantiation epoch, then hands the verdict
// to the domain's Decide function.
//
// It only reads. Deciding (and any shutdown consequence) belongs to the caller,
// so the daemon never drains itself from this package.
package drain package drain
import ( import (
@@ -62,11 +57,8 @@ func readPid1Start() (int64, error) {
return parseProcStat(string(data)) return parseProcStat(string(data))
} }
// parseProcStat extracts PID 1's start time (field 22, starttime) from the // parseProcStat returns field 22 (starttime) of a /proc/[pid]/stat record,
// textual /proc/[pid]/stat record. The comm field (field 2) is wrapped in // parsing after the last ')'.
// parentheses and may itself contain spaces or parentheses, so the record is
// split after the last closing parenthesis and field 22 is the 20th token
// there (post-paren token 0 is field 3, the state).
func parseProcStat(stat string) (int64, error) { func parseProcStat(stat string) (int64, error) {
paren := strings.LastIndexByte(stat, ')') paren := strings.LastIndexByte(stat, ')')
if paren < 0 { if paren < 0 {
@@ -107,14 +99,8 @@ func New(markerPath string, epoch func() (drain.Epoch, error)) *Reader {
return &Reader{path: markerPath, epoch: epoch} return &Reader{path: markerPath, epoch: epoch}
} }
// Check returns the drain decision for the marker at the reader's path against // Check returns the drain decision for the marker. A missing marker is
// the current epoch. // DecisionNone; any read failure is reported and never drains.
//
// A missing marker returns DecisionNone. The returned error is informational --
// it exists so a caller can log why a request was not honoured -- but the
// decision is authoritative and always fails closed on an unrecoverable read
// (permission error, malformed JSON, unreadable epoch) so a broken marker can
// never drain the daemon.
func (r *Reader) Check() (drain.Decision, error) { func (r *Reader) Check() (drain.Decision, error) {
data, err := os.ReadFile(r.path) data, err := os.ReadFile(r.path)
if errors.Is(err, os.ErrNotExist) { if errors.Is(err, os.ErrNotExist) {
@@ -14,13 +14,8 @@ import (
// it can tell a credential is wired without ever holding it. // it can tell a credential is wired without ever holding it.
const Sentinel = "archie-proxy-managed" const Sentinel = "archie-proxy-managed"
// CredentialKind is how one run carries a credential service. The org's // CredentialKind is how a run carries a credential service, decided by the
// binding decides it, never the Kit's declaration: the sandbox kit spec lets // org's binding. An absent service is not carried.
// one credential@1 declare apiKey and oauth together, meaning "whichever the
// host has bound" (docker/claude-code-kit declares both for anthropic, codex
// for openai). A service absent from a session's bound kinds is not carried
// at all, which is what refuses a required credential and skips an optional
// one.
type CredentialKind string type CredentialKind string
const ( const (
+3 -6
View File
@@ -153,12 +153,9 @@ func (p *Proxy) injectOAuth(ctx context.Context, s *Session, r *http.Request, ho
return nil return nil
} }
// interceptOAuth handles one request to a granted rule's token endpoint // interceptOAuth proxies a token endpoint request, swapping the sentinel
// whole. A refresh carrying the sentinel refresh token goes upstream with // refresh token for the stored one. Successful responses are stored and
// the stored real one; a login code exchange carries none and passes as // returned to the container with sentinels.
// sent. A successful response is captured to the store and reaches the
// container with sentinels in place of the real tokens, so a refreshed
// token is never returned to it.
func (p *Proxy) interceptOAuth(ctx context.Context, w http.ResponseWriter, r *http.Request, s *Session, rule oauthRule, scheme, target string) { func (p *Proxy) interceptOAuth(ctx context.Context, w http.ResponseWriter, r *http.Request, s *Session, rule oauthRule, scheme, target string) {
body, err := io.ReadAll(io.LimitReader(r.Body, maxTokenExchange)) body, err := io.ReadAll(io.LimitReader(r.Body, maxTokenExchange))
if err != nil { if err != nil {
+3 -6
View File
@@ -80,12 +80,9 @@ type SessionOptions struct {
Run string Run string
Org string Org string
Network *spec.PhasedNetwork Network *spec.PhasedNetwork
// Credentials is what the Kit's descriptor declares; Bound is how the run // Credentials are what the Kit declares; Bound maps each service the run
// actually carries them, each service the run credential names mapped to // carries to its kind. A rule fires only for a service bound with the same
// the kind the org's binding gave it. Declared and bound are two separate // kind.
// facts, and neither widens the other: a rule may only fire for a service
// the run carries as that same kind, and a service the run carries not at
// all resolves as unbound whichever rule asks.
Credentials []spec.CredentialCapability Credentials []spec.CredentialCapability
Bound map[string]CredentialKind Bound map[string]CredentialKind
} }
+5 -18
View File
@@ -41,18 +41,9 @@ type Options struct {
Timeout time.Duration Timeout time.Duration
} }
// New builds an embedding client from cfg.Models[Role] and the matching // New builds an embedding client from cfg.Models[Role] and its provider. It
// cfg.Providers entry. It reports (nil, false) rather than an error when // returns (nil, false) when unavailable. Provider secrets must already be
// the capability is not usable right now -- no role configured, an unknown // resolved.
// provider, an unsupported provider class, or a missing/blank credential
// -- per the credential-missing-degrades-not-fatal rule (AGENTS.md):
// callers must skip the capability, never fail daemon startup or an
// unrelated call, over this.
//
// cfg.Providers is expected to already have secret refs resolved to
// APIKeyEnv (see internal/app/archied/provider_secrets.go's
// resolveProviderSecrets), the same precondition agentexec.NewRuntime
// relies on for chat models.
func New(cfg config.Config, opts Options) (domainembedding.Client, bool) { func New(cfg config.Config, opts Options) (domainembedding.Client, bool) {
getenv := opts.Getenv getenv := opts.Getenv
if getenv == nil { if getenv == nil {
@@ -103,12 +94,8 @@ func parseModelRef(ref string) (providerID, modelID string, ok bool) {
return providerID, modelID, true return providerID, modelID, true
} }
// newSDKProvider constructs the ai-sdk embed.Provider for a config class. // newSDKProvider builds the ai-sdk embed provider for class. Unsupported
// Only classes matching config.Provider's shape (APIKey/BaseURL, no // classes, including azure, return an error.
// provider-specific extra fields) are supported -- azure's Deployment
// requirement, for example, has no field to source it from yet, so an
// "azure" class degrades like any other unsupported class rather than
// gaining a special-cased partial wiring.
func newSDKProvider(class, apiKey, baseURL string, httpClient *http.Client) (sdkembed.Provider, error) { func newSDKProvider(class, apiKey, baseURL string, httpClient *http.Client) (sdkembed.Provider, error) {
switch class { switch class {
case "openai", "openai-compatible": case "openai", "openai-compatible":
+2 -7
View File
@@ -17,13 +17,8 @@ import (
// token lifecycle. // token lifecycle.
const tokenMetadataKey = "gateway-token" const tokenMetadataKey = "gateway-token"
// TargetIsLoopback reports whether addr's host is a loopback address. Both // TargetIsLoopback reports whether addr's host is a loopback IP or
// literal loopback IPs (127.0.0.1, ::1) and the "localhost" hostname count; // "localhost".
// everything else (including the wildcard 0.0.0.0 and DNS names) is treated
// as network-reachable and therefore non-loopback. It applies to a listen
// address and a dial target alike -- the same host decides both. It mirrors
// staterpc.TargetIsLoopback; the two transports keep their own copy so
// neither adapter imports the other.
func TargetIsLoopback(addr string) (bool, error) { func TargetIsLoopback(addr string) (bool, error) {
host, _, err := net.SplitHostPort(addr) host, _, err := net.SplitHostPort(addr)
if err != nil { if err != nil {
+3 -9
View File
@@ -8,15 +8,9 @@ import (
"google.golang.org/grpc/credentials/insecure" "google.golang.org/grpc/credentials/insecure"
) )
// Dial returns a chat contract client for target, the standalone // Dial returns a Gateway chat client for target. A loopback target dials
// archie-gateway process, applying the transport security boundary: a // insecure; any other target requires a token. The cleanup closes the
// loopback target dials insecure with no credential, while a non-loopback // connection.
// target requires a Bearer [REDACTED] and fails closed without one. The returned
// cleanup closes the connection.
//
// The rule lives here rather than in a composition root so the server side
// (which decides whether to install the token interceptors) and every client
// that dials it share one implementation. It mirrors staterpc.Dial.
func Dial(target, token string, options ...grpc.DialOption) (*Client, func(), error) { func Dial(target, token string, options ...grpc.DialOption) (*Client, func(), error) {
target = strings.TrimSpace(target) target = strings.TrimSpace(target)
if target == "" { if target == "" {
@@ -11,14 +11,8 @@ import (
var _ messaging.SessionStore = (*StoreClient)(nil) var _ messaging.SessionStore = (*StoreClient)(nil)
// StoreClient implements messaging.SessionStore over the chat service's // StoreClient implements messaging.SessionStore over the Gateway's session
// session-store RPCs. It is separate from Client (the ChatContract view) // RPCs. Role is derived from the session.
// because the two contracts serve different reads over the same messages.
//
// Role does not cross the wire (the proto is unchanged by the messaging
// migration). Both sides derive it from the owning session instead -- the
// server on write, this client on read -- so they agree without a proto
// change.
type StoreClient struct{ client pb.ChatServiceClient } type StoreClient struct{ client pb.ChatServiceClient }
func NewStoreClient(conn grpc.ClientConnInterface) *StoreClient { func NewStoreClient(conn grpc.ClientConnInterface) *StoreClient {
@@ -10,12 +10,8 @@ import (
"github.com/samcharles93/archie-core/internal/domain/taskactions" "github.com/samcharles93/archie-core/internal/domain/taskactions"
) )
// taskActionCodes pairs each sentinel the daemon's action service reports // taskActionCodes maps task-action sentinels to the gRPC codes that carry
// with the gRPC code that carries it. The dashboard picks its HTTP status by // them.
// matching these (404, 409, 503), and gRPC transports a code and a string,
// not a Go error, so the class travels as the code and is restored on
// arrival. Adding a sentinel a caller matches on without adding it here
// silently degrades that case to a 500.
var taskActionCodes = []struct { var taskActionCodes = []struct {
code codes.Code code codes.Code
err error err error
+2 -11
View File
@@ -177,12 +177,7 @@ func intPointer(v *int64) *int {
return &n return &n
} }
// attachmentProtoList renders a message's attachments in wire shape for the // attachmentProtoList converts attachments without their Data.
// stored-history and outbound-event directions. Data is deliberately
// unmapped: those directions must not carry a turn's bytes, and a persisted
// record strips them too. An attachment with no fields beyond Data would
// produce an empty wire message, which is still the honest encoding of
// "metadata was stripped", and never happens for a real attachment.
func attachmentProtoList(media []messaging.MediaAttachment) []*pb.Media { func attachmentProtoList(media []messaging.MediaAttachment) []*pb.Media {
if len(media) == 0 { if len(media) == 0 {
return nil return nil
@@ -197,11 +192,7 @@ func attachmentValueList(list []*pb.Media) []messaging.MediaAttachment {
return mapValues(list, attachmentValue) return mapValues(list, attachmentValue)
} }
// inboundAttachmentProtoList renders a turn's attachments for the inbound // inboundAttachmentProtoList converts attachments including their Data.
// request. Unlike the stored direction, Data rides along: the channel
// frontend downloads the file, but the Gateway process that runs the turn
// never holds the platform credential, so the bytes have no other way to
// reach the model.
func inboundAttachmentProtoList(media []messaging.MediaAttachment) []*pb.Media { func inboundAttachmentProtoList(media []messaging.MediaAttachment) []*pb.Media {
if len(media) == 0 { if len(media) == 0 {
return nil return nil
+4 -15
View File
@@ -9,11 +9,7 @@ import (
"github.com/docker/sandbox-kit-spec/v3/spec" "github.com/docker/sandbox-kit-spec/v3/spec"
) )
// Credential-file placeholders, the vocabulary the Kit spec's // Credential-file placeholders.
// credentialFile.structure declares. A leaf may reference the token
// sentinels as a whole value or inside a larger string; ExpiresAt (a number)
// and Scopes (an array) may only be the whole value, and PrimaryApiKey's
// enclosing key is dropped rather than substituted.
const ( const (
accessPlaceholder = "{{.AccessToken}}" accessPlaceholder = "{{.AccessToken}}"
refreshPlaceholder = "{{.RefreshToken}}" refreshPlaceholder = "{{.RefreshToken}}"
@@ -28,11 +24,8 @@ const (
credentialFileMode = "0600" credentialFileMode = "0600"
) )
// renderCredentialFile renders c's oauth.credentialFile: the declared structure // renderCredentialFile renders c's oauth credential file with sentinels for
// with the Kit's sentinels substituted for the token placeholders, the stored // tokens and the stored scopes and expiry.
// token set's scopes for {{.Scopes}} and its expiry for {{.ExpiresAt}}, encoded
// in the declared format. facts is the only thing the renderer receives about
// the stored token set, so a real token cannot reach the file.
func renderCredentialFile(c spec.CredentialCapability, facts OAuthFacts) (string, error) { func renderCredentialFile(c spec.CredentialCapability, facts OAuthFacts) (string, error) {
cf := c.OAuth.CredentialFile cf := c.OAuth.CredentialFile
var sentinels spec.Sentinels var sentinels spec.Sentinels
@@ -64,11 +57,7 @@ func substitutePlaceholders(v any, sentinels spec.Sentinels, scopes []string, ex
case map[string]any: case map[string]any:
out := make(map[string]any, len(t)) out := make(map[string]any, len(t))
for k, e := range t { for k, e := range t {
// {{.PrimaryApiKey}}'s spec case is that its ENCLOSING KEY is omitted // No key is ever captured, so drop the enclosing key.
// when no key is captured. archie resolves a service key only to fill
// the egress grant and the container holds egress.Sentinel, so there
// is never a key to render here: drop the key, never empty it (absent
// and empty are different bugs). Do not "fix" this into a value.
if s, ok := e.(string); ok && s == primaryKeyPlaceholder { if s, ok := e.(string); ok && s == primaryKeyPlaceholder {
continue continue
} }
+4 -11
View File
@@ -1,8 +1,5 @@
// Package kit decides whether archie can run a harness packaged as Kit v3 // Package kit decides whether archie can run a Kit v3 harness and with what
// images, and what it runs with. Descriptor grammar, validation and // capabilities.
// composition belong to the Kit spec package; this package owns only the
// runtime's half of the contract: which capability types archie implements,
// and the refusals that keep the host's guarantees intact.
package kit package kit
import ( import (
@@ -151,12 +148,8 @@ func FromMerge(merged *spec.MergeResult) (*Plan, error) {
return plan, nil return plan, nil
} }
// ValidateNeeds rejects a Plan that cannot meet what the workflow's stages // ValidateNeeds rejects a Plan without a resume verb when the gate may
// declared they need: a // retry.
// gate that may retry needs the Kit's agent-sessions resume verb, because
// archie resumes the session with the gate's output rather than starting
// over. gateRetries is zero for a workflow with no gated stage, which no
// Kit composition can fail to meet.
func ValidateNeeds(plan *Plan, gateRetries int) error { func ValidateNeeds(plan *Plan, gateRetries int) error {
if gateRetries > 0 && (plan.Sessions == nil || len(plan.Sessions.Resume) == 0) { if gateRetries > 0 && (plan.Sessions == nil || len(plan.Sessions.Resume) == 0) {
return fmt.Errorf("needs.gate_retries is %d, but the kit declares no %s resume verb to retry with", gateRetries, typeAgentSessions) return fmt.Errorf("needs.gate_retries is %d, but the kit declares no %s resume verb to retry with", gateRetries, typeAgentSessions)
+6 -16
View File
@@ -59,12 +59,8 @@ type LaunchParams struct {
Execution string Execution string
ProxyToken string ProxyToken string
CAPath string CAPath string
// Bound keys each credential service this run carries to the kind the // Bound maps each credential service the run carries to its kind. Values
// org's binding gave it (egress.CredentialKind). A service absent from // never leave the host.
// this map is unbound: its mode variable says none, it renders no
// credential file, and the proxy refuses (required) or skips (optional)
// any request needing it. The map carries kinds, never values -- the real
// secret stays on the host.
Bound map[string]egress.CredentialKind Bound map[string]egress.CredentialKind
// OAuth is the non-secret facts of each bound OAuth credential's stored // OAuth is the non-secret facts of each bound OAuth credential's stored
// token set, keyed by service, that a Kit's credentialFile renders: the // token set, keyed by service, that a Kit's credentialFile renders: the
@@ -162,11 +158,8 @@ func Assemble(p *Plan, img ImageConfig, params LaunchParams) (Launch, error) {
return l, nil return l, nil
} }
// credentialFiles renders the credential file of every OAuth-bound // credentialFiles renders the credential file for each OAuth-bound
// credential whose Kit declares one: the path and structure the Kit names, // credential that declares one.
// with the stored token set's scopes and expiry. A service bound as an API
// key renders none -- its Kit may carry the OAuth declaration too, but this
// run has no token set to put in the file.
func credentialFiles(creds []spec.CredentialCapability, bound map[string]egress.CredentialKind, oauth map[string]OAuthFacts) ([]spec.File, error) { func credentialFiles(creds []spec.CredentialCapability, bound map[string]egress.CredentialKind, oauth map[string]OAuthFacts) ([]spec.File, error) {
var files []spec.File var files []spec.File
for _, c := range creds { for _, c := range creds {
@@ -182,11 +175,8 @@ func credentialFiles(creds []spec.CredentialCapability, bound map[string]egress.
return files, nil return files, nil
} }
// contextFiles materializes agent-context@1: the workload's profile file // contextFiles writes agent-context@1: a profile file beside the workspace
// beside the workspace, never in it, carrying an index of each Kit's body. // indexing each Kit's body.
// A staged body is pointed at where the image holds it; an inline one is
// written to its own file beside the profile. The profile never inlines a
// Kit's text, so stacking Kits does not grow what the agent always loads.
func contextFiles(p *Plan) ([]spec.File, error) { func contextFiles(p *Plan) ([]spec.File, error) {
ac, err := spec.AgentContextOf(p.Capabilities) ac, err := spec.AgentContextOf(p.Capabilities)
if err != nil || ac == nil || ac.Filename == "" { if err != nil || ac == nil || ac.Filename == "" {
+11 -39
View File
@@ -61,13 +61,8 @@ type Launcher struct {
// Kit container: the worker's own binary and the egress CA. // Kit container: the worker's own binary and the egress CA.
AgentBinary string AgentBinary string
CAFile string CAFile string
// Config is read fresh on every Launch, never captured once at // Config is read on every Launch. Nil Secrets or Grants leave every
// construction: credential bindings are their own live control-plane // credential unbound.
// resource (controlplane.CredentialBindingsKind), so a binding added or
// changed after this daemon started must take effect on the very next
// dispatch, the same way an agent profile already does. A nil Secrets or
// Grants degrades every credential to unbound rather than panicking: a
// daemon with no Kit profile configured wires neither.
Config *config.Holder Config *config.Holder
Secrets SecretResolver Secrets SecretResolver
Grants Grants Grants Grants
@@ -91,11 +86,8 @@ type Request struct {
Adapter string Adapter string
WorkDir string WorkDir string
WorkerEnv []string WorkerEnv []string
// GateRetries is the workflow's declared gate-retry budget // GateRetries is the workflow's gate-retry budget. Launch refuses a positive
// (task.WorkflowNeeds.GateRetries); zero means no stage gates its // budget without a resume verb.
// result. A composition with no agent-sessions resume verb cannot meet
// a positive one, and Launch refuses it rather than starting a
// container no gate failure could ever resume.
GateRetries int GateRetries int
// Org and GrantedServices are the dispatching identity's own facts. A Kit // Org and GrantedServices are the dispatching identity's own facts. A Kit
// credential resolves only where these agree with a configured // credential resolves only where these agree with a configured
@@ -181,23 +173,10 @@ func (l *Launcher) Launch(ctx context.Context, req Request) (*Run, error) {
return run, nil return run, nil
} }
// resolveCredentials computes the run's granted secrets -- the intersection // resolveCredentials resolves the run's credentials: services declared by
// of what the Kit composition declares, what config.CredentialBinding // the Kit, bound in config, and granted to the identity's org. granted maps
// entries exist, and what the dispatching identity is granted and belongs // run/service to value; kinds maps service to bound kind. A binding with a
// to -- and resolves each to a real value. granted is the run/service -> // secret is an API key; one without is the org's OAuth token set.
// value map for Grants.Grant; kinds is the service -> bound-kind map
// kit.Assemble renders the container's credential state from. A service
// failing any part of the intersection, or whose binding's secret does not
// resolve, is simply absent from both: it stays unbound, exactly as if
// credential@1 named a service nobody configured.
//
// The binding decides the kind, not the Kit's declaration: the sandbox kit
// spec lets one credential declare apiKey and oauth together, meaning
// "whichever the host has bound" (docker/claude-code-kit declares both for
// anthropic). A binding naming a secret is therefore this run's API key even
// when the Kit also declares OAuth, and a binding naming none is the org's
// stored OAuth token set, carried with no value because the proxy reads the
// tokens itself.
func (l *Launcher) resolveCredentials(req Request, creds []spec.CredentialCapability) (granted map[string]string, kinds map[string]egress.CredentialKind) { func (l *Launcher) resolveCredentials(req Request, creds []spec.CredentialCapability) (granted map[string]string, kinds map[string]egress.CredentialKind) {
granted = map[string]string{} granted = map[string]string{}
kinds = map[string]egress.CredentialKind{} kinds = map[string]egress.CredentialKind{}
@@ -217,11 +196,7 @@ func (l *Launcher) resolveCredentials(req Request, creds []spec.CredentialCapabi
bindings := config.ContainerConfig{Credentials: current}.BoundCredentials(req.Org, req.GrantedServices, declared) bindings := config.ContainerConfig{Credentials: current}.BoundCredentials(req.Org, req.GrantedServices, declared)
for service, binding := range bindings { for service, binding := range bindings {
if binding.Secret == (config.SecretRef{}) { if binding.Secret == (config.SecretRef{}) {
// The binding names no secret of its own. Only a Kit declaring // No secret: only OAuth gives the service a value.
// OAuth gives the service a meaning then -- the org's captured
// token set. Anything else has nothing to carry and stays
// unbound, rather than resolving to an empty value the proxy
// would present as a credential.
if !oauth[service] { if !oauth[service] {
continue continue
} }
@@ -242,11 +217,8 @@ func (l *Launcher) resolveCredentials(req Request, creds []spec.CredentialCapabi
return granted, kinds return granted, kinds
} }
// oauthFacts reads the stored token set's scopes and expiry for each // oauthFacts reads the stored scopes and expiry for each OAuth-bound
// OAuth-bound credential whose Kit renders a credential file. The store is // credential with a credential file.
// read only for a service this run bound as OAuth, and only those facts
// leave here: the tokens stay behind, so the renderer has no way to write
// one.
func (l *Launcher) oauthFacts(ctx context.Context, org string, creds []spec.CredentialCapability, kinds map[string]egress.CredentialKind) (map[string]kit.OAuthFacts, error) { func (l *Launcher) oauthFacts(ctx context.Context, org string, creds []spec.CredentialCapability, kinds map[string]egress.CredentialKind) (map[string]kit.OAuthFacts, error) {
facts := map[string]kit.OAuthFacts{} facts := map[string]kit.OAuthFacts{}
for _, c := range creds { for _, c := range creds {
@@ -1,8 +1,5 @@
// Package builtin implements the built-in, file-backed MemoryProvider. It // Package builtin is a file-backed markdown memory store: "## " sections of
// persists agent memory to MEMORY.md and USER.md as plain markdown, using // blank-line-separated blocks.
// "## " headers to delimit named sections. Content within a section is
// organized into blank-line-separated blocks; add/replace/remove act on
// those blocks and on substrings within them.
package builtin package builtin
import ( import (
@@ -1,10 +1,3 @@
// Adapted from /work/apps/tau/internal/providers/snapshot/gen/main.go at
// b41dda42ef869cc919044ff4f23d7b568531c3f5.
//
// Deliberate mutations:
// - runtime startup fetch and disk fallback replace build-time generation;
// - every models.dev provider is eligible rather than a Tau-owned allowlist;
// - usable providers are derived from live environment and Archie overrides.
package modelcatalog package modelcatalog
import ( import (
+2 -8
View File
@@ -58,14 +58,8 @@ func NewFlow(ctx context.Context, cfg Config, clientID, clientSecret, redirectUR
}, nil }, nil
} }
// AuthCodeURL returns the provider URL to send a browser to, and the PKCE // AuthCodeURL returns the provider URL to send a browser to, with the
// verifier the callback must present with the code. // audience requested, and the PKCE verifier.
//
// The audience is requested HERE, at the authorization endpoint, and not only at
// the token endpoint: a provider that returns the audience empty otherwise mints
// a token this dashboard must refuse, and the refusal looks like a signing fault
// rather than a missing request parameter. The verifier is generated by the
// library, not by archie.
func (f *Flow) AuthCodeURL(state string) (string, string) { func (f *Flow) AuthCodeURL(state string) (string, string) {
codeVerifier := oauth2.GenerateVerifier() codeVerifier := oauth2.GenerateVerifier()
url := f.oauth.AuthCodeURL(state, url := f.oauth.AuthCodeURL(state,
+2 -7
View File
@@ -77,13 +77,8 @@ func (v *Verifier) Verify(ctx context.Context, rawToken string) (identity.Creden
}, nil }, nil
} }
// subjectFor derives the caller a token asserts. // subjectFor returns the token's subject: sub for a person, client_id for a
// // machine. A token with neither is refused.
// A person's token carries sub, the provider's stable identifier for that person.
// A machine's token carries no sub at all and identifies its caller by client_id,
// so a machine identity is keyed on the client and one identity exists per client
// registration. A token asserting neither identifies nobody and is refused rather
// than being accepted as an anonymous caller.
func subjectFor(issuer, subject, clientID string) (identity.Subject, error) { func subjectFor(issuer, subject, clientID string) (identity.Subject, error) {
switch { switch {
case strings.TrimSpace(subject) != "": case strings.TrimSpace(subject) != "":
+5 -18
View File
@@ -12,14 +12,8 @@ import (
"strings" "strings"
) )
// extractTarGz extracts a gzipped tar stream into destDir, stripping a single // extractTarGz extracts a .tar.gz into destDir, stripping a common top-level
// common leading path component when every entry shares one (the wrapper // directory. It skips .git and refuses paths escaping destDir.
// directory GitHub's and Gitea's repository archives both add, named after the
// repo and ref -- e.g. "acme-widget-deadbeef/"). A.git entry is never written:
// PRSource's isolation contract requires the pipeline to read a.git-free
// snapshot, and a malicious PR's own tarball is exactly the input this cannot
// trust, so an entry escaping destDir via ".." or an absolute path is refused
// rather than silently written outside it.
func extractTarGz(r io.Reader, destDir string) error { func extractTarGz(r io.Reader, destDir string) error {
gz, err := gzip.NewReader(r) gz, err := gzip.NewReader(r)
if err != nil { if err != nil {
@@ -73,11 +67,7 @@ func planExtraction(tr *tar.Reader) (prefix string, entries []tarEntry, err erro
top, _, hasSlash := strings.Cut(name, "/") top, _, hasSlash := strings.Cut(name, "/")
switch { switch {
case !hasSlash && hdr.Typeflag != tar.TypeDir: case !hasSlash && hdr.Typeflag != tar.TypeDir:
// A bare top-level file (no directory component at all) proves // A top-level file means there is no wrapper directory.
// there is no single wrapper directory containing everything. A
// bare top-level *directory* entry is not this evidence -- it is
// exactly the wrapper directory's own header, which real
// archives include alongside the files nested under it.
commonPrefix = "" commonPrefix = ""
first = false first = false
case first: case first:
@@ -99,11 +89,8 @@ func planExtraction(tr *tar.Reader) (prefix string, entries []tarEntry, err erro
return commonPrefix, entries, nil return commonPrefix, entries, nil
} }
// writeEntry writes one archive entry under destDir, with prefix (if any) // writeEntry writes one directory or regular file under destDir; other
// stripped from its name. destDir is the absolute destination directory // entry types are skipped.
// resolved by extractTarGz. Directories, regular files, and nothing else
// are written: a symlink or device entry from an untrusted PR archive is
// skipped rather than followed.
func writeEntry(destDir, prefix string, e tarEntry) error { func writeEntry(destDir, prefix string, e tarEntry) error {
name := path.Clean(filepath.ToSlash(e.header.Name)) name := path.Clean(filepath.ToSlash(e.header.Name))
if name == "." || name == prefix { if name == "." || name == prefix {
+6 -18
View File
@@ -17,21 +17,12 @@ import (
// package's reader cannot drift into two different paths. // package's reader cannot drift into two different paths.
const PrefetchDirName = ".archie-pr-review" const PrefetchDirName = ".archie-pr-review"
// MountSource implements workflow.PRSource by reading data the daemon // MountSource implements workflow.PRSource from data the daemon prefetched
// already fetched and wrote to disk before the container started, instead of // into baseDir:
// calling the forge itself. This is how the sandboxed pipeline gets pull
// request data with no forge credential ever entering the container: the
// daemon (which holds the credential) runs Source (this package's
// HTTP-backed implementation) against baseDir before handing the container
// off, and the pipeline's Stage.Run bodies read the result through
// MountSource instead.
//
// baseDir holds three artifacts, all written by prefetchTo (the daemon-side
// counterpart, in internal/daemon):
// //
// metadata.json -- {"title", "body", "head_sha"} // metadata.json -- {"title", "body", "head_sha"}
// diff.patch -- the raw unified diff // diff.patch -- the unified diff
// snapshot/ -- the extracted repository tree at head_sha // snapshot/ -- the repository tree at head_sha
type MountSource struct { type MountSource struct {
baseDir string baseDir string
} }
@@ -81,11 +72,8 @@ func (s *MountSource) Diff(_ context.Context, _, _ string, _ int) (string, error
return string(data), nil return string(data), nil
} }
// Snapshot copies the prefetched snapshot tree into destDir and returns the // Snapshot copies the prefetched snapshot into destDir and returns its head
// head SHA it was measured against. This is a local filesystem copy inside // SHA.
// the same container -- no network call, no credential -- since the daemon
// already extracted the archive into baseDir/snapshot before the container
// started.
func (s *MountSource) Snapshot(_ context.Context, _, _ string, _ int, destDir string) (string, error) { func (s *MountSource) Snapshot(_ context.Context, _, _ string, _ int, destDir string) (string, error) {
m, err := s.readMetadata() m, err := s.readMetadata()
if err != nil { if err != nil {
+3 -16
View File
@@ -1,14 +1,5 @@
// Package prsource implements workflow.PRSource: fetching an arbitrary // Package prsource fetches a pull request's metadata, diff and head snapshot
// external pull request's metadata, diff and a read-only snapshot of its // over the forge HTTP API.
// head, for the pr-review pipeline. It is
// the PR-under-review counterpart to worktree.Manager's use as the task's
// own Trees: that path only ever reaches the task's own worktree, never a
// third-party PR being reviewed.
//
// Every call goes over the forge's HTTP API -- never a git-shell checkout. The
// pipeline's Stage.Run bodies execute inside the sandboxed archie-agent
// process, which holds no forge credential and no git-level credential either;
// a git clone would need one.
package prsource package prsource
import ( import (
@@ -19,11 +10,7 @@ import (
"github.com/samcharles93/archie-core/internal/domain/workflow" "github.com/samcharles93/archie-core/internal/domain/workflow"
) )
// PullRequest is the pull request fields Metadata, Diff and Snapshot need: // PullRequest is the PR's title, body and head SHA.
// title, body, and the head commit SHA the diff's line numbers and the
// snapshot are both measured against. It mirrors forge.PullRequest's shape
// so callers can pass that type directly without this package importing
// internal/forge.
type PullRequest struct { type PullRequest struct {
Title string Title string
Body string Body string
+5 -25
View File
@@ -1,13 +1,4 @@
// Package readiness implements the readiness probes declared by // Package readiness implements the health probes.
// internal/domain/health. Each probe is a thin adapter over a real subsystem
// dependency: it answers with a live, current result rather than a constant,
// so an operator calling /health/detailed sees the daemon's true state.
//
// The probes are deliberately dependency-light and injectable. Each takes
// the narrowest useful shape -- an interface it defines, a function, or a
// value -- so a probe never reaches into the daemon or a broad registry for
// its inputs. Composition root wiring (internal/app/archied) builds the
// concrete values and assembles the domain Registry.
package readiness package readiness
import ( import (
@@ -59,11 +50,8 @@ func (p *StoreProbe) Check(ctx context.Context) health.Result {
// --- remote contract --- // --- remote contract ---
// ContractProbe reports whether a service this process consumes over the wire // ContractProbe checks that a remote service answers a cheap call within a
// answers a cheap call within a bounded timeout. It is the readiness signal // timeout.
// available to a process that depends on a service it does not own: the probe
// consumes the dependency's own result and never inspects its manager, registry
// or database.
type ContractProbe struct { type ContractProbe struct {
ProbeName string ProbeName string
Timeout time.Duration Timeout time.Duration
@@ -210,16 +198,8 @@ func NewDiskProbeTargets(targets []DiskTarget) *DiskProbe {
func (p *DiskProbe) Name() string { return "disk" } func (p *DiskProbe) Name() string { return "disk" }
// reduceTargets collapses the configured targets to one per path: the first // reduceTargets keeps one target per path, in first-seen position, with the
// target seen for a path wins its position, and the result keeps the strictest // strictest requirement for that path.
// requirement any target placed on that path.
//
// Position is what makes this necessary rather than using a plain set. With
// root, an optional /var, then a required data path that resolves to /var, the
// optional /var is the target that survives dedup -- and its optional rules
// then apply to a path the daemon requires, so a vanished required path is
// skipped as "optional absent" and the probe reports OK. Choosing the required
// target (and its name) keeps the failure visible and correctly attributed.
func reduceTargets(targets []DiskTarget) []DiskTarget { func reduceTargets(targets []DiskTarget) []DiskTarget {
index := make(map[string]int, len(targets)) index := make(map[string]int, len(targets))
out := make([]DiskTarget, 0, len(targets)) out := make([]DiskTarget, 0, len(targets))
@@ -21,14 +21,8 @@ type Adapter struct {
agentID string agentID string
} }
// NewAdapter builds an Adapter that reports agentID as the agent owning // NewAdapter returns an Adapter that reports agentID as every session's
// every session it returns, so the curator addresses agent-user memory to // agent.
// the same agent a chat turn reads it back from (the composition's
// configured bot user, the value gateway.TurnRunnerConfig.BotUser carries).
// A session record's own Source.BotUser is deliberately not used for this:
// it is the router's session-resolution match key, and empty in a
// single-identity deployment. Roles come from the canonical records the
// store returns, so no bot identity is needed to derive them.
func NewAdapter(store gateway.SessionStore, agentID string) *Adapter { func NewAdapter(store gateway.SessionStore, agentID string) *Adapter {
return &Adapter{store: store, agentID: agentID} return &Adapter{store: store, agentID: agentID}
} }
@@ -18,13 +18,8 @@ const Name = "session-memory"
// written. // written.
const ActionExtracted = "memory.extracted" const ActionExtracted = "memory.extracted"
// ActionSkipped records a session the pass could not address, so nothing was // ActionSkipped records a session that could not be attributed, with the
// written for it. The reason names what was missing: an agent id (the // reason.
// deployment's bot user, empty when the composition resolved none), how many
// distinct senders were found (zero for a dashboard or webhook session, more
// than one for a group chat), and how many user messages carried no sender at
// all -- unknown provenance rules a session out on its own, beside any number
// of identified senders.
const ActionSkipped = "memory.skipped" const ActionSkipped = "memory.skipped"
// DefaultInterval is the check-in cadence used when nothing more // DefaultInterval is the check-in cadence used when nothing more
@@ -130,13 +125,9 @@ func effectiveSince(since, now time.Time) time.Time {
return since return since
} }
// reviewOne extracts observations from one session's recent messages and // reviewOne extracts observations from one session and writes them as
// writes them through engine as agent-user memory for the session's single // agent-user memory for its single participant. It returns nil when nothing
// participant. Returns nil (no Action) when nothing was extracted -- // was extracted, or a skip action when the session cannot be attributed.
// matching the skill curator's "a pass with nothing to report is not an
// error" -- or when the session carries no messages at all. A session the
// pass cannot address -- no agent, or no single participant -- is skipped
// with an Action saying why.
func (c *Curator) reviewOne(ctx context.Context, engine domainmemory.MemoryEngine, sess curator.SessionSummary) (*curator.Action, error) { func (c *Curator) reviewOne(ctx context.Context, engine domainmemory.MemoryEngine, sess curator.SessionSummary) (*curator.Action, error) {
msgs, err := c.host.Conversations.Messages(ctx, sess.ID, messageTailSize) msgs, err := c.host.Conversations.Messages(ctx, sess.ID, messageTailSize)
if err != nil { if err != nil {
@@ -146,17 +137,7 @@ func (c *Curator) reviewOne(ctx context.Context, engine domainmemory.MemoryEngin
return nil, nil return nil, nil
} }
// Resolve the address before spending a model call: an unaddressable // Skip sessions without an agent before calling the model.
// session has nowhere to write, so there is nothing a model response
// could add. ScopeAgentUser is addressed by both ids, and a guess would
// file one person's facts under another's.
//
// An empty agent id is the composition having resolved no bot user for
// this deployment -- the session's own record cannot supply one (see
// Adapter). The engine would refuse the scope, which is the right
// refusal for a write with no address: what is wrong is writing it at
// all, so the skip belongs here, at the point the scope is produced, and
// not as a Pass error that abandons every other session's work.
if sess.AgentID == "" { if sess.AgentID == "" {
return &curator.Action{ return &curator.Action{
At: c.host.Clock.Now(), At: c.host.Clock.Now(),
@@ -197,12 +178,7 @@ func (c *Curator) reviewOne(ctx context.Context, engine domainmemory.MemoryEngin
facts = facts[:maxObservationsPerSession] facts = facts[:maxObservationsPerSession]
} }
// Agent-user is the only defensible home for a derived fact about a // Write to agent-user scope, which chat turns read back.
// person: agent scope would leak user A's facts to user B through the
// same agent, user scope would pool them across agents, and the session
// id this used to write stops meaning anything when the session ends.
// ScopeAgentUser is also what a later chat turn reads back, which is
// the whole point of writing these at all.
scope := domainmemory.Scope{ scope := domainmemory.Scope{
Kind: domainmemory.ScopeAgentUser, Kind: domainmemory.ScopeAgentUser,
Agent: domainmemory.AgentID(sess.AgentID), Agent: domainmemory.AgentID(sess.AgentID),
@@ -229,18 +205,9 @@ func (c *Curator) reviewOne(ctx context.Context, engine domainmemory.MemoryEngin
}, nil }, nil
} }
// sessionParticipant returns the one participant a session's memory may be // sessionParticipant returns the session's single user-role sender, or why
// attributed to, or -- when there is none -- the reason there isn't. // there is none. Any user message without a sender makes the session
// // unattributable.
// Only user-role messages carry a person: an assistant message carries the
// bot, so it can never manufacture a participant.
//
// A user-role message with an empty SenderID is part of the excerpt the
// model reads but names nobody, so the session is unattributable outright,
// even beside exactly one identified sender. The alternative -- skipping it
// and attributing the rest -- would credit whoever that sender is with
// facts drawn from content of unknown provenance, which is the isolation
// failure the agent-user scope exists to prevent.
func sessionParticipant(msgs []curator.ConversationMessage) (participant, reason string) { func sessionParticipant(msgs []curator.ConversationMessage) (participant, reason string) {
senders := make(map[string]struct{}) senders := make(map[string]struct{})
unidentified := 0 unidentified := 0
@@ -88,12 +88,8 @@ func (c *Curator) Pass(ctx context.Context, in curator.PassInput) (curator.PassR
return curator.PassResult{Actions: actions}, nil return curator.PassResult{Actions: actions}, nil
} }
// reviewOne classifies a single skill and, for a normalizable one, // reviewOne classifies one skill and writes back a normalized version when
// writes the cleaned content back. It never returns more than one // possible. It returns at most one Action.
// Action: a parse failure and a missing field can't both be reported for
// the same skill in the same pass (a Frontmatter that failed to parse
// has no fields to check), and a normalization is reported once even
// though it may have fixed multiple lines.
func (c *Curator) reviewOne(ctx context.Context, name string) ([]curator.Action, error) { func (c *Curator) reviewOne(ctx context.Context, name string) ([]curator.Action, error) {
sk, err := c.host.Skills.Read(ctx, name) sk, err := c.host.Skills.Read(ctx, name)
if err != nil { if err != nil {
+6 -23
View File
@@ -21,11 +21,7 @@ const skillsDir = ".agents/skills"
// its own directory under skillsDir. // its own directory under skillsDir.
const skillFile = "SKILL.md" const skillFile = "SKILL.md"
// Store implements curator.SkillStore over one root directory's. // Store implements curator.SkillStore over root's */SKILL.md files.
// agents/skills/*/SKILL.md files. List and Read never parse frontmatter
// themselves beyond a best-effort Description: a per-skill parse failure is the
// curator's problem to report as an Action, not this store's problem to abort
// on.
type Store struct { type Store struct {
root string root string
} }
@@ -43,13 +39,8 @@ func (s *Store) skillPath(name string) string {
return filepath.Join(s.skillsPath(), name, skillFile) return filepath.Join(s.skillsPath(), name, skillFile)
} }
// List returns every skill directory under root, in directory order. A // List returns every skill directory with a SKILL.md. A missing directory
// directory with no SKILL.md is skipped -- consistent with internal/skill's // returns an empty list.
// Catalog, which treats an unreadable or absent SKILL.md as "no skill here"
// rather than an error -- and a missing
// skills directory returns an empty list, not an error, matching
// internal/skill's discovery convention (missing directory is not an
// error).
func (s *Store) List(_ context.Context) ([]curator.SkillRef, error) { func (s *Store) List(_ context.Context) ([]curator.SkillRef, error) {
entries, err := os.ReadDir(s.skillsPath()) entries, err := os.ReadDir(s.skillsPath())
if os.IsNotExist(err) { if os.IsNotExist(err) {
@@ -73,12 +64,8 @@ func (s *Store) List(_ context.Context) ([]curator.SkillRef, error) {
return refs, nil return refs, nil
} }
// Read returns the named skill's raw SKILL.md content. Description is a // Read returns the skill's raw SKILL.md. Description is empty when the
// best-effort frontmatter read: empty on a parse failure, which Read // frontmatter does not parse.
// does not treat as an error -- Pass is what decides a parse failure is
// worth reporting, and it needs the raw Content to do so via its own
// skill.Parse call regardless of whether this convenience field could be
// populated.
func (s *Store) Read(_ context.Context, name string) (curator.Skill, error) { func (s *Store) Read(_ context.Context, name string) (curator.Skill, error) {
path := s.skillPath(name) path := s.skillPath(name)
data, err := os.ReadFile(path) data, err := os.ReadFile(path)
@@ -92,11 +79,7 @@ func (s *Store) Read(_ context.Context, name string) (curator.Skill, error) {
return sk, nil return sk, nil
} }
// Write persists s.Content to the named skill's SKILL.md. The skill's // Write overwrites an existing skill's SKILL.md.
// directory must already exist -- Write curates an existing skill, it
// does not create a new one, which is a bigger decision (naming,
// directory layout, an author writing the rest of the frontmatter) that
// this store does not make.
func (s *Store) Write(_ context.Context, sk curator.Skill) error { func (s *Store) Write(_ context.Context, sk curator.Skill) error {
dir := filepath.Join(s.skillsPath(), sk.Name) dir := filepath.Join(s.skillsPath(), sk.Name)
if info, err := os.Stat(dir); err != nil || !info.IsDir() { if info, err := os.Stat(dir); err != nil || !info.IsDir() {
+6 -19
View File
@@ -23,24 +23,15 @@ import (
// execution; the standalone Gateway never mutates the task store directly. // execution; the standalone Gateway never mutates the task store directly.
const actionSubject = "archie.gateway.task-action" const actionSubject = "archie.gateway.task-action"
// Identity is a pointer because its absence is meaningful: nil is a // actionRequest is a task action request. A nil Identity is a caller acting
// caller authenticated across identities, which the daemon's service // across identities. A nil Actor records an unattributed action.
// distinguishes from any named identity, empty included. It is a SCOPE -- which
// tasks the caller may touch -- and never an actor.
//
// Actor carries who performed the action and whose authority permitted it, as
// resolved by the caller that verified the credential. Its absence is meaningful:
// an absent actor records an unattributed action, never a human's.
type actionRequest struct { type actionRequest struct {
Identity *string `json:"identity"` Identity *string `json:"identity"`
TaskID int64 `json:"task_id"` TaskID int64 `json:"task_id"`
Action taskstate.Action `json:"action"` Action taskstate.Action `json:"action"`
Actor *actorPayload `json:"actor,omitempty"` Actor *actorPayload `json:"actor,omitempty"`
// Instructions and Findings are the review gate answer payload // Instructions and Findings answer the review gate. RetryMode is the retry's
// (taskactions.ActionPayload). They are empty for every action but // worktree mode; empty means refresh_onto_base.
// approve and rereview, and for chat surfaces, which carry no selection
// syntax. RetryMode is the worktree choice a retry carries; empty means
// the explicit default, refresh_onto_base.
Instructions string `json:"instructions,omitempty"` Instructions string `json:"instructions,omitempty"`
Findings []string `json:"findings,omitempty"` Findings []string `json:"findings,omitempty"`
RetryMode taskstate.RetryMode `json:"retry_mode,omitempty"` RetryMode taskstate.RetryMode `json:"retry_mode,omitempty"`
@@ -114,12 +105,8 @@ func actionErrorFor(kind string, err error) error {
return err return err
} }
// Register exposes only identity-scoped operator actions on the daemon. The // Register serves identity-scoped task actions over NATS. Handlers use
// daemon retains execution cancellation, retry policy, forge closure and event // context.Background().
// ownership; the Gateway's client reaches this responder over NATS.
// Handlers run with context.Background() (the storerpc convention): the
// daemon's lifecycle ctx is not request-scoped, and a cancelled boot ctx must
// not poison later requests.
func Register(nc *nats.Conn, service taskactions.Service, log *slog.Logger) (func(), error) { func Register(nc *nats.Conn, service taskactions.Service, log *slog.Logger) (func(), error) {
return natsrpc.RegisterAll(nc, []natsrpc.Registration{{ return natsrpc.RegisterAll(nc, []natsrpc.Registration{{
Subject: actionSubject, Subject: actionSubject,
+3 -15
View File
@@ -20,11 +20,7 @@ func (s Store) TaskByID(ctx context.Context, id int64) (*taskactions.Task, error
return &taskactions.Task{ID: t.ID, Owner: t.Owner, Repo: t.Repo, Identity: t.Identity, Status: t.Status, ParkReason: t.ParkReason, IssueNumber: t.IssueNumber, RetryCount: t.RetryCount, Attempt: t.Attempt, Branch: t.Branch, RetryMode: t.RetryMode, ForgeBacked: t.IsForgeBacked(), ReviewGate: t.ReviewGate, RereviewRounds: t.RereviewRounds}, nil return &taskactions.Task{ID: t.ID, Owner: t.Owner, Repo: t.Repo, Identity: t.Identity, Status: t.Status, ParkReason: t.ParkReason, IssueNumber: t.IssueNumber, RetryCount: t.RetryCount, Attempt: t.Attempt, Branch: t.Branch, RetryMode: t.RetryMode, ForgeBacked: t.IsForgeBacked(), ReviewGate: t.ReviewGate, RereviewRounds: t.RereviewRounds}, nil
} }
// CancelExecution delegates to the store's one cancel path. // CancelExecution delegates to the store.
// Both adapters -- the
// PostgreSQL store and the remote gRPC client -- implement it; the type
// assertion failing would be a composition bug, so it is named rather than
// panicked over.
func (s Store) CancelExecution(ctx context.Context, taskID int64, reason, to string) ([]int64, error) { func (s Store) CancelExecution(ctx context.Context, taskID int64, reason, to string) ([]int64, error) {
canceller, ok := s.TaskStore.(storecontract.ExecutionCanceller) canceller, ok := s.TaskStore.(storecontract.ExecutionCanceller)
if !ok { if !ok {
@@ -33,11 +29,7 @@ func (s Store) CancelExecution(ctx context.Context, taskID int64, reason, to str
return canceller.CancelExecution(ctx, taskID, reason, to) return canceller.CancelExecution(ctx, taskID, reason, to)
} }
// RespondReviewGate delegates to the store's guarded response write. Both // RespondReviewGate delegates to the store.
// adapters -- the PostgreSQL store and the remote gRPC client -- implement it
// (internal/domain/storecontract.ReviewGateResponder); the type assertion
// failing would be a composition bug, so it is named rather than panicked
// over, exactly like CancelExecution above.
func (s Store) RespondReviewGate(ctx context.Context, taskID int64, fromStatus, gate string, rereview bool, maxRounds int) error { func (s Store) RespondReviewGate(ctx context.Context, taskID int64, fromStatus, gate string, rereview bool, maxRounds int) error {
responder, ok := s.TaskStore.(storecontract.ReviewGateResponder) responder, ok := s.TaskStore.(storecontract.ReviewGateResponder)
if !ok { if !ok {
@@ -52,11 +44,7 @@ func MaxRetries(cfg *config.Holder) func(*taskactions.Task) int {
return 0 return 0
} }
c := cfg.Get() c := cfg.Get()
// A multi-identity deployment declares its repositories under // In multi-identity deployments, repos live under the task's identity.
// [[identities.repos]] and has no global [[repos]] at all, so the
// task's owning identity is the only place a per-repo override can
// live. Without this lookup the override is never matched and the
// task dies at the global cap instead of the configured one.
if t.Identity != "" { if t.Identity != "" {
for _, identity := range c.Identities { for _, identity := range c.Identities {
if identity.Name != t.Identity { if identity.Name != t.Identity {
Loaded 100 of 141 files, more files were not shown because too many files have changed in this diff. Show more