refactor(postgres,mcp,archieui,task,prreview,playbook): cut comments down to what the code does

This commit is contained in:
sam committed 2026-10-03 22:01:54 +10:00
1 parent 2fc11b60e1
commit 1bd738cfe8
38 files changed
+209 -827

No files matched your search

+4 -19
View File
@@ -10,18 +10,8 @@ import (
"github.com/samcharles93/archie-core/internal/infrastructure/oidc"
)
// dashboardAuthenticator builds the dashboard's credential check from the
// endpoint references the process was given, or returns nil when none were.
//
// It is built here rather than in the command because cmd/ parses flags and
// nothing else, and it takes two URLs rather than a configuration struct because
// this process is deliberately kept unaware of the config file's shape -- see the
// note above Options. Issuer and audience are exactly the endpoint references
// Options already carries for the Gateway and the State Store.
//
// A nil result means no provider is configured, and the shared token stays the
// gate: an instance that never configured one keeps working, and its requests are
// recorded unattributed rather than credited to a human.
// dashboardAuthenticator builds the OIDC credential check, or nil when no
// provider is configured.
func dashboardAuthenticator(ctx context.Context, opts Options, subjects identity.SubjectResolver, log *slog.Logger) (func(context.Context, string) (identity.Identity, error), error) {
if strings.TrimSpace(opts.OidcIssuer) == "" {
return nil, nil
@@ -41,13 +31,8 @@ func dashboardAuthenticator(ctx context.Context, opts Options, subjects identity
}, nil
}
// dashboardLoginFlow builds the browser sign-in flow from endpoint references and
// the operator's registration, or returns nil when none is configured.
//
// The secret is read from the environment variable the operator named and never
// logged, printed or stored. A client id is optional: an instance that only
// accepts agent tokens configures none, and then there is simply no sign-in
// route -- token verification is unaffected.
// dashboardLoginFlow builds the browser sign-in flow, or nil when not
// configured. The client secret is read from the named env var.
func dashboardLoginFlow(ctx context.Context, opts Options) (identity.LoginFlow, error) {
if strings.TrimSpace(opts.OidcIssuer) == "" || strings.TrimSpace(opts.OidcClientID) == "" {
return nil, nil
+9 -29
View File
@@ -42,11 +42,8 @@ type deps struct {
Denials access.DenialStore
}
// compose builds the dashboard server for the UI process from contract-backed
// dependencies only. Fields left at zero are daemon-local handles; their
// handlers answer 501/503 or empty. Config writes stay with the daemon. Task
// logs are read through the State Store, and this process is the only listener
// for POST /webhooks/capture/{source}.
// compose builds the dashboard server from contract-backed dependencies.
// Unset fields answer 501/503 or empty.
func compose(d deps) *webui.Server {
srv := &webui.Server{
Store: d.Store,
@@ -84,12 +81,8 @@ func compose(d deps) *webui.Server {
if bindings, ok := d.Store.(storecontract.BindingStore); ok {
srv.Bindings = bindings
}
// Harness OAuth token sets are a ratified State Store contract, and the
// same client already carries them. Withholding it would leave the
// harness page answering 503 on a deployment that has the store.
// The setup terminal itself is not wired here: its
// implementation owns a container, which this process must not link, so
// the route stays a documented 503 until a daemon-side contract exists.
// Harness token status comes from the State Store; the setup terminal is not
// available here.
if secrets, ok := d.Store.(storecontract.HarnessSecretStore); ok {
srv.HarnessSecrets = secrets
}
@@ -99,12 +92,7 @@ func compose(d deps) *webui.Server {
if d.Chat != nil {
srv.Chat = &webui.ChatService{Contract: d.Chat}
}
// The task-log read crosses the State Store contract: the files live in
// the state directory that process owns, so this one asks for the log
// rather than opening a path. Withholding
// it would degrade a page that has an owner, and would leave the dashboard
// claiming task logging was not enabled -- see wireTaskLogs.
// The policy chain: wired together or not at all
// The policy chain: wired together or not at all.
srv.Access = d.Access
srv.Principals = d.Principals
srv.Denials = d.Denials
@@ -128,12 +116,8 @@ func wireTaskLogs(d deps, srv *webui.Server) {
srv.TaskLogs = logs
}
// wireCaptureSurfaces attaches the capture read, the source editor and the
// intake receiver. All resolve from d.Store's contracts: CaptureStore backs
// the inspector's list and the mapping preview's scan window, SourceStore
// resolves the source whose signing setting verifies an event. A store that
// does not implement one degrades that half with a warning rather than
// aborting the process, mirroring the daemon's own adapter selection.
// wireCaptureSurfaces attaches capture listing, source editing and intake. A
// store missing a contract degrades that part with a warning.
func wireCaptureSurfaces(d deps, srv *webui.Server) {
captures, hasCaptures := d.Store.(storecontract.CaptureStore)
sources, hasSources := d.Store.(storecontract.SourceStore)
@@ -164,12 +148,8 @@ func wireCaptureSurfaces(d deps, srv *webui.Server) {
}
}
// captureArrivalPublisher persists a capture's arrival event through the
// State Store, where the daemon's bus drain persists every other activity
// event; the event pump then delivers it to every connected browser. A nil
// store records captures without announcing them (compose's test-only
// shape); an insert failure is logged, not surfaced -- the capture row is
// already durable, and the inspector refetches on its next view.
// captureArrivalPublisher persists a capture's arrival event. Failures are
// logged.
func captureArrivalPublisher(d deps) func(context.Context, events.Event) {
if d.Store == nil {
return nil
+4 -38
View File
@@ -12,18 +12,8 @@ import (
"github.com/samcharles93/archie-core/internal/webui"
)
// Resolve produces the effective Options: flag values win, and a field the
// operator left empty falls back to the configuration file's projection, then
// to a process default. It ends with validate, so a caller that gets no error
// holds a startable configuration.
//
// The projection is an allowlist of the values this process needs --
// [services.gateway].{target,target_token}, [services.state].{target,
// target_token}, [web].{listen,trust_forwarded_headers} and [capture]. The UI
// reads the same file the daemon does because operators already keep the
// service endpoints there, but Options has no field for anything else in it:
// the daemon's forge credentials, model catalog, workflow routing, NATS
// settings, filesystem jail and agent/container settings have nowhere to land
// Resolve returns the effective Options: flags first, then the config file's
// projection, then defaults, and validates the result.
func Resolve(o Options, log *slog.Logger) (Options, error) {
if o.Config != "" {
cfg, found, err := readProjection(o.Config, o.Overlay, log)
@@ -87,24 +77,7 @@ func project(cfg config.Config) projection {
}
}
// withEnvTokens fills a service token the operator gave neither on the command
// line nor in [services.*].target_token. The config loader does not expand
// environment variables, and config.example.toml documents the environment as
// how a remote consumer presents these tokens, so without this a deployment
// that supplies them by env dials with an empty bearer and staterpc.Dial
// refuses a non-loopback start.
//
// It runs here rather than inside project() because the process is fully
// drivable by flags: readProjection returns early when there is no config
// file, so a fallback living in the file's projection would miss exactly the
// flags-only deployment that needs it.
//
// This reads the process environment only. The daemon resolves the same names
// through a secret.Registry, which also consults bws and any Yaegi-loaded
// engine; the UI process deliberately does not compose that runtime, because
// ui-service-boundary.md's deletion gate forbids a secret runtime package
// here. A token held in a secret manager must therefore be exported into
// archie-ui's environment by whatever starts it.
// withEnvTokens fills service tokens left unset from the environment.
func withEnvTokens(o Options) Options {
if o.Gateway.Token == "" {
o.Gateway.Token = os.Getenv("GATEWAY_TOKEN")
@@ -155,14 +128,7 @@ func merge(o Options, p projection) Options {
}
func withDefaults(o Options) Options {
// This is the one config key the UI and the daemon read with opposite
// meanings: in the daemon, Web.Listen = "off" disables the dashboard
// (config.Config "off" is a sentinel, not an address). In a dedicated UI
// process there is no sense disabling the only thing it does, so "off"
// falls through to the default listener. None of the other projected
// values is overloaded this way; if "off" ever means something else here
// it must be pinned with a test, because it is exactly where an operator
// preparing the split would set it.
// "off" disables the daemon's dashboard but means the default listener here.
if o.Listen == "" || o.Listen == "off" {
o.Listen = defaultListen
}
+8 -30
View File
@@ -1,14 +1,5 @@
// Package archieui composes the standalone UI Service: the operator-facing
// HTTP surface and the compiled SPA, served against a Gateway and a State
// Store running in other processes.
//
// The two rules that shape this package are that the UI owns only process-local
// settings ("HTTP listen address and read/header/shutdown timeouts; UI asset
// source or build mode; UI authentication mode and token reference; Gateway
// endpoint and credential reference; State Store endpoint and credential
// reference; readiness endpoint and dependency timeout policy"), and that it
// "must never implement [configuration] policy by holding or mutating a shared
// config.Holder".
// Package archieui composes the standalone dashboard service, talking to the
// Gateway and State Store over their contracts.
package archieui
import (
@@ -55,18 +46,12 @@ type Options struct {
// use. It is the explicit opt-in to a non-loopback listener: without it
// a reachable bind must be given a token.
TokenFile string
// OidcIssuer and OidcAudience are endpoint references for the identity
// provider, not configuration. The issuer is read for its discovery document
// and signing keys, and the audience is the resource identifier this process
// accepts credentials for. Both empty leaves the shared-token gate in place;
// an issuer with no audience is refused rather than accepted without the check.
// OidcIssuer and OidcAudience configure the identity provider. Both empty
// keeps the shared token; an issuer without an audience is refused.
OidcIssuer string
OidcAudience string
// OidcClientID and OidcClientSecretEnv are the provider registration for the
// browser sign-in. The secret itself is never a flag: the flag names the
// environment variable holding it, so it cannot reach a process listing or a
// log line. No client id means no sign-in flow, which is what an instance
// that only accepts agent tokens wants.
// OidcClientID and OidcClientSecretEnv register the browser sign-in; the
// secret is read from the named env var. No client ID disables sign-in.
OidcClientID string
OidcClientSecretEnv string
// OidcRedirectURL is the callback the provider returns the browser to. Its
@@ -77,15 +62,8 @@ type Options struct {
// operator did not say, and the file (else false) decides.
TrustForwardedHeaders *bool
// Capture configures the unbound webhook capture receiver this process
// mounts on its bypass mux. At the
// cutover this process is the only listener
// serving POST /webhooks/capture/{source}: the receiver persists what
// arrives through the State Store contract, and the daemon's
// binding-dispatch loop consumes captures from the same store, so the
// HTTP front door moves without moving the owner of work intake. Zero
// fields fall back to configuration.DefaultCapture, the same defaults a
// decoded config would carry.
// Capture configures the webhook capture receiver. Zero fields use
// configuration.DefaultCapture.
Capture CaptureOptions
// Gateway and State are the two remote contracts the dashboard consumes.
+2 -7
View File
@@ -10,13 +10,8 @@ import (
"github.com/samcharles93/archie-core/internal/infrastructure/readiness"
)
// newReadinessRegistry builds the registry behind GET /health/detailed. The
// UI is ready when both of its mandatory remote contracts answer within the
// dependency timeout; each probe consumes the dependency's own result over
// the wire and never inspects its manager, registry or database
//
// The component names match the daemon dashboard's, so the readiness view
// reads the same whichever process serves it.
// newReadinessRegistry builds the readiness probes for the Gateway and State
// Store.
func newReadinessRegistry(o Options, tasks storecontract.TaskStore, chat messaging.ChatContract, problems []infraaccess.Problem) *health.Registry {
return health.NewRegistry(
readiness.NewProblemProbe("access_policies", problems),
+4 -12
View File
@@ -20,13 +20,8 @@ import (
"github.com/samcharles93/archie-core/internal/webui"
)
// buildAccessChain loads the stored policies over the wire and builds the
// engine. The wire client satisfies the two access contracts the dashboard
// needs alongside the engine.
// buildAccessChain loads the stored policies over the wire and builds the
// engine. A State Store serving no policies has no chain to evaluate: the
// dashboard degrades to the credential check rather than refusing to serve,
// so an unavailable policy store is a warning, not a boot failure.
// buildAccessChain loads stored policies and builds the access engine. With
// no policies it returns nil and logs a warning.
func buildAccessChain(ctx context.Context, store *staterpc.Client, log *slog.Logger) (access.Authorizer, []infraaccess.Problem, error) {
stored, err := store.ListPolicies(ctx)
if err != nil {
@@ -138,11 +133,8 @@ func Run(ctx context.Context, options Options) error {
return serve(ctx, listener, srv.Handler(), opts)
}
// serve runs handler on listener until ctx ends, then shuts the HTTP server
// down within ShutdownTimeout so in-flight dashboard requests finish before
// the contract clients close. A graceful shutdown that overruns its deadline
// is a normal shutdown under load, not a process failure: the remaining
// connections are force-closed and serve reports clean.
// serve runs handler until ctx ends, then shuts down within
// ShutdownTimeout.
func serve(ctx context.Context, listener net.Listener, handler http.Handler, opts Options) error {
server := &http.Server{Handler: handler, ReadHeaderTimeout: opts.ReadHeaderTimeout}
serveErr := make(chan error, 1)
+3 -11
View File
@@ -10,17 +10,9 @@ import (
"github.com/samcharles93/archie-core/internal/domain/storecontract"
)
// InvokeOnce runs one playbook action at most once per
// (playbook, version, event, action) tuple, record-before-invoke: the ledger
// row is committed before fn runs, so a redelivered action (the same
// structural key) skips without repeating a non-revocable side effect.
// The structural key is computed
// from Decision.PlaybookID, Decision.Version, input.TaskID (the event_id) and
// Decision.ActionID; when the action declares no id the 1-based
// Decision.ActionPosition is used instead -- it is never a CEL expression. A
// key with an empty component (or no fallback position) is rejected before
// the ledger write rather than recorded as a degenerate row that collapses
// distinct events onto one key.
// InvokeOnce runs fn at most once per (playbook, version, event, action),
// recording the ledger row first. The action's id, or its position, keys the
// action; a key with an empty part is refused.
func InvokeOnce(ctx context.Context, ledger storecontract.PlaybookDispatcher, log *slog.Logger, decision Decision, input DispatchInput, fn func(context.Context) error) error {
if decision.ActionID == "" && decision.ActionPosition < 1 {
return fmt.Errorf("playbook action has no id and no 1-based position (playbook_id=%q)", decision.PlaybookID)
+23 -114
View File
@@ -1,18 +1,5 @@
// Package playbook is the EDA playbook document type and its event coordinator:
// the rich trigger+actions YAML shape with CEL `when` conditions and `args`
// values (open question 1, resolved to CEL). A playbook is one of two shapes
// (multi-action-playbooks.md, D2):
//
// - a workflow playbook is exactly one `workflow` action, unchanged from
// the original boundary, and is routed by the daemon's definition pin;
// - an action playbook is one or more `module` actions in order, each with
// a registered `kind`, `args`, and an optional `when`/`id`. Store.Run
// executes it.
//
// The two shapes never mix in one playbook. This is an ADDITIONAL routing
// source alongside the flat kind/label binding files: the daemon consults a
// matching workflow playbook before those bindings when it pins a task's
// workflow definition. The binding loaders themselves are untouched.
// Package playbook loads EDA playbooks: a trigger plus either one workflow
// action or ordered module actions, with CEL `when` and `args`.
package playbook
import (
@@ -59,12 +46,7 @@ type Store struct {
// Playbook is one trigger+actions document.
type Playbook struct {
// ID is the playbook's stable identity for execution-time idempotency:
// its file path relative to the configured directory root. It is unique
// within a single Load because the EDA loader walks one directory's
// entries and filenames there are inherently unique -- the doc's claim
// about "the directory-loader's collision rule" belongs to the ROUTING
// loader (workflow.LoadPlaybookDirs), a different loader.
// ID is the playbook's path relative to the directory root.
ID string
// Version is a content hash of the loaded file, recomputed on every
// load. It pins dispatched-run provenance to the exact definition active
@@ -93,11 +75,7 @@ type Trigger struct {
// routed yet.
type Action struct {
Position string
// ID is an optional stable identifier for this action. When present it
// is the key later actions read this action's result under
// (actions.<id>). Workflow actions use the shared stable-identifier
// grammar; module actions must use a CEL identifier so the id can be
// read through `actions.<id>` field selection.
// ID optionally names this action so later actions can read actions.<id>.
ID string
// Kind is the module kind name (position: module only); empty for a
// workflow action.
@@ -111,12 +89,8 @@ type Action struct {
// Nil or empty means the action takes no args.
Args map[string]*expr.Program
// env is the per-action CEL environment this action's expressions were
// compiled against: the prior actions' declared ids and their kinds'
// Result types. It is compile-only: expr.Env.Eval reads only the
// compiled Program (the cost limit is baked in at Compile) and never
// reads the Env receiver. It is unset only for a hand-built Action
// (tests, pre-load composition); loaded actions always carry it.
// env is the CEL environment this action's expressions were compiled
// against.
env *expr.Env
}
@@ -178,12 +152,7 @@ func at(path string, line int) string {
return fmt.Sprintf("%s:%d", path, line)
}
// Module action ids are stricter than workflow ids because they must also be
// readable as `actions.<id>` in CEL field selection. The authoritative check
// is expr.IsCELFieldName (which compiles the probe), plus a lowercase policy:
// the id must be a lowercase CEL field name, so `Build` -- a valid CEL
// identifier -- is rejected for its case, while a CEL keyword such as `in` is
// rejected because `actions.in` has no field-selection spelling.
// Module action ids must be lowercase CEL field names.
// validateActionIDs enforces the WORKFLOW id shape and uniqueness. An absent
// id is fine (ids are optional); a declared id must match the
@@ -229,14 +198,8 @@ func validateModuleActionIDs(path string, actions []rawAction) error {
return nil
}
// Load reads every *.yaml/*.yml playbook in dir, validates each against the
// two-shape boundary (exactly one workflow action, or one or more module
// actions; never mixed), and compiles each when expression and args value
// against the action's per-playbook environment. ANY failure -- malformed
// YAML, a mixed/unsupported/empty action shape, an unknown kind, a when
// compile error, an args key error -- fails the whole load: the reject-at-load
// philosophy of the parent design doc. A missing directory is an empty store
// (matching the flat binding loaders' convention).
// Load reads and compiles every playbook in dir. Any invalid playbook fails
// the load. A missing directory is an empty store.
func Load(dir string, modules Modules) (*Store, error) {
entries, err := os.ReadDir(dir)
if os.IsNotExist(err) {
@@ -360,11 +323,8 @@ func compileActions(path string, raw []rawAction, schemas KindSchemas) ([]Action
}
}
// validateActionShapeField rejects a field from the other shape being present
// on an action: a workflow action must not declare kind (module-only), and a
// module action must not declare workflow (workflow-only). yaml.Unmarshal
// accepts both keys, so this is where a silently-ignored foreign key becomes
// a reported load failure naming the playbook and the action index.
// validateActionShapeField rejects a field belonging to the other action
// shape.
func validateActionShapeField(path string, i int, pos string, a *rawAction) error {
switch pos {
case "workflow":
@@ -505,14 +465,8 @@ func checkArgType(path, label, kind string, argsSchema reflect.Type, key string,
return nil
}
// compileArgs compiles every args value as a CEL expression at load, keyed by
// arg name. J2 has no literal/expression split: the YAML scalar text IS the
// CEL source, so a string literal is quoted inside YAML and a number or
// context read is written as CEL. When argsSchema is non-nil (a module kind's
// Args struct) every key must name one of its fields; workflow actions pass
// nil and keep free-form args. Each program goes through the same
// compile/reference validation as `when`, with label naming the offending
// action and the args key naming the offending field.
// compileArgs compiles each args value as CEL. With argsSchema, every key
// must name one of its fields.
func compileArgs(path string, lines map[string]int, label, kind string, raw map[string]string, env *expr.Env, argsSchema reflect.Type) (map[string]*expr.Program, error) {
if len(raw) == 0 {
return nil, nil
@@ -543,12 +497,7 @@ func compileArgs(path string, lines map[string]int, label, kind string, raw map[
return args, nil
}
// validateArgsKeys rejects an args key the kind's Args struct does not define
// (multi-action-playbooks.md, D4), so an arg typo is a load failure rather
// than a dispatch-time shape mismatch. Go field names are lower-cased to the
// YAML spelling (Message -> message), and the YAML key is compared verbatim:
// the decoder also matches literal lower-case keys, so `Message` is rejected
// here rather than loading and then failing at dispatch.
// validateArgsKeys rejects args keys the kind's Args struct does not define.
func validateArgsKeys(path string, lines map[string]int, label, kind string, argsSchema reflect.Type, raw map[string]string) error {
t := argsSchema
if t.Kind() == reflect.Pointer {
@@ -575,14 +524,7 @@ func validateArgsKeys(path string, lines map[string]int, label, kind string, arg
return nil
}
// compileExpr compiles one playbook expression and applies the remaining
// load-time reference check: every `actions` read must be statically
// resolvable to a prior action id. The per-playbook object type rejects an
// undeclared or forward id and a dynamic `actions` read at compile time; the
// one spelling it does not reject is a bare `actions` value read, which this
// check still refuses. field is the human-readable expression location used in
// errors (`when condition` or `args["name"]`), so a failure names the
// playbook path and the offending expression.
// compileExpr compiles one expression and rejects a bare `actions` read.
func compileExpr(path, field, src string, env *expr.Env) (*expr.Program, error) {
prg, err := env.Compile(strings.TrimSpace(src))
if err != nil {
@@ -605,13 +547,7 @@ type DispatchInput struct {
Labels []string
// Kind is the routing kind the labels produced (workintake.KindForLabels).
Kind string
// TaskID is the originating task's identity, used to derive the event_id
// half of the playbook_dispatches idempotency ledger key. It carries the
// TaskEnvelope.IdempotencyKey() value ("archie:owner/repo/number"), the
// stable identity available at the discovery/dispatch point (pollNATS and
// the webhook receiver both compute kind/labels from a TaskEnvelope before
// any workflow.Task row exists). It is NOT a workflow.Task.ID int64, which
// does not exist until the task is persisted.
// TaskID is the originating task's idempotency key, used as the event id.
TaskID string
// Event is the event payload exposed as `event` in CEL expressions. For
// a workflow-kind dispatch this carries the label/kind fields cheaply
@@ -619,11 +555,8 @@ type DispatchInput struct {
Event map[string]any
}
// IsActionPlaybook reports whether pb is an action playbook (one or more
// module actions), as opposed to a workflow playbook (exactly one workflow
// action). It is the single two-shape predicate shared by Dispatch (which
// routes only workflow playbooks) and Run (which executes only action
// playbooks), so the two can never disagree.
// IsActionPlaybook reports whether pb has module actions rather than a
// workflow action.
func (pb *Playbook) IsActionPlaybook() bool {
return len(pb.Actions) != 1 || pb.Actions[0].Position != "workflow"
}
@@ -654,11 +587,8 @@ func (pb *Playbook) Match(input DispatchInput) bool {
return true
}
// Decision is what the coordinator selected for one event: the workflow a
// matching playbook's action names, plus the provenance of the definition
// that chose it. Version pins the decision to the exact file content active
// when it fired, and both fields are the first two components of the
// per-action idempotency key the resolved gap-2 scheme derives
// Decision is the workflow a matching playbook selected, with its playbook
// id and version.
type Decision struct {
PlaybookID string
Version string
@@ -673,21 +603,8 @@ type Decision struct {
ActionPosition int
}
// Dispatch returns the workflow name the first matching workflow playbook
// selects for the input, and whether any playbook matched. Action playbooks
// choose no workflow, so they are skipped here and executed by Run. No match
// means trigger
// mismatch or a when condition evaluating false, and the caller keeps its own
// routing.
//
// The name is returned rather than a compiled workflow because the production
// caller (the daemon's definition pin) decides against the active definition
// collection, not against a compiled registry; whether the named workflow
// exists is that caller's check, in the same place it makes it for every
// other routing source.
//
// A when evaluation error follows the resolved doc's J3: the condition
// evaluates to false and dispatch is skipped (the caller logs).
// Dispatch returns the workflow the first matching workflow playbook names,
// and whether one matched. A `when` error counts as false.
func (s *Store) Dispatch(input DispatchInput) (Decision, bool) {
// Nil-receiver-safe: a composition root that builds its daemon before the
// playbook load hands over a nil store, and "no playbooks" is the honest
@@ -723,15 +640,7 @@ func evalContext(input DispatchInput) expr.Context {
}
}
// EvalArgs evaluates a compiled action's args against the dispatch context,
// returning the resulting name->value map. Run evaluates args the same way
// against a context that also carries earlier actions' results. An action declaring no args evaluates to an empty map, nil-program entries
// are skipped, and the first evaluation error is returned. Nil-receiver-safe
// for the pre-load composition phase.
//
// Asymmetry with `when`: `when` is a predicate, so an evaluation error is
// false (J3: skip + log); `args` is data, so an evaluation error has no
// meaningful substitute and is returned to the caller to abort the playbook run
// EvalArgs evaluates an action's args and returns the first error.
func (s *Store) EvalArgs(a Action, input DispatchInput) (map[string]any, error) {
if s == nil {
return map[string]any{}, nil
+3 -5
View File
@@ -11,11 +11,9 @@ import (
"github.com/samcharles93/archie-core/internal/domain/storecontract"
)
// Run executes every action playbook whose trigger matches input, in load
// order. Each action goes through
// InvokeOnce, so it fires at most once per (playbook, version, event,
// action). A failure stops only its own playbook; the rest still run, and
// the failures are returned joined, each naming its playbook and action.
// Run executes every matching action playbook in load order, each action at
// most once. A failure stops only its playbook; failures are returned
// joined.
func (s *Store) Run(ctx context.Context, ledger storecontract.PlaybookDispatcher, log *slog.Logger, input DispatchInput) error {
if s == nil {
return nil
+6 -24
View File
@@ -13,17 +13,8 @@ import (
"strings"
)
// BlastRadius returns the files inside fsys that a change reaches without
// touching: the files that import a changed file, and the files a changed file
// imports. It is the review's other half -- a line that breaks its callers
// still compiles, so the callers have to be read even though the diff never
// mentions them.
//
// Paths are relative to fsys's root and are matched as the diff wrote them. An
// import that cannot be resolved to a file inside fsys -- a standard library
// package, a node module, a file this snapshot does not carry -- contributes
// nothing: a guessed path would put a file nobody can open into the review's
// scope.
// BlastRadius returns the files that import a changed file or that a changed
// file imports. Unresolvable imports are ignored.
func BlastRadius(fsys fs.FS, changed []string) ([]string, error) {
graph, err := buildImportGraph(fsys)
if err != nil {
@@ -51,11 +42,8 @@ func BlastRadius(fsys fs.FS, changed []string) ([]string, error) {
return radius, nil
}
// ExposureCounts returns, for every file the change reaches without touching,
// how many changed files reach it: a fan-in count computed from the same
// import graph BlastRadius walks. It is BlastRadius's detail, not its
// replacement -- the coverage gate needs to tell a file three unrelated
// changed files each reach apart from one only one of them happens to import.
// ExposureCounts returns, for each file BlastRadius reaches, how many changed
// files reach it.
func ExposureCounts(fsys fs.FS, changed []string) (map[string]int, error) {
graph, err := buildImportGraph(fsys)
if err != nil {
@@ -174,14 +162,8 @@ func modulePath(fsys fs.FS) (string, error) {
return "", nil
}
// goPackageFiles maps every Go import path this snapshot owns to the files
// that package contains. The module path is what turns a directory into an
// import path, so an import resolves only when a directory of the snapshot
// really is the package that path names.
//
// A _test.go file is left out: it is never part of what an importer compiles,
// so no import path resolves to one. A test file's own imports are still edges
// of its own -- a test that exercises the change is read with it.
// goPackageFiles maps each Go import path in the snapshot to its non-test
// files.
func goPackageFiles(paths []string, module string) map[string][]string {
if module == "" {
return nil
+2 -10
View File
@@ -10,16 +10,8 @@ type Budget struct {
WallClock time.Duration
}
// PhaseExhausted reports whether phase (1-based, counting the phase about to
// start) has already spent its share, given how much of the run's total
// budget every phase up to and including it is allotted out of phases total.
//
// The check is against the cumulative allotment through phase, not phase's
// own isolated slice: an earlier phase's underspend is not wasted, but its
// overspend still eats into a later phase's share. That is what "a phase
// whose share is spent is skipped" means for a phase that has not started
// yet and so has spent nothing of its own -- the run's spend so far is
// compared against how much the whole run should have spent by this point.
// PhaseExhausted reports whether the run's spend exceeds the cumulative share
// allotted through phase (1-based) of phases.
func (b Budget) PhaseExhausted(phase, phases, tokensSpent int, elapsed time.Duration) bool {
if phase <= 0 || phases <= 0 {
return false
+12 -53
View File
@@ -1,12 +1,5 @@
// Package prreview is the deterministic core of the PR review pipeline: diff
// parsing, change clustering, blast radius, evidence extraction, scoring,
// deduplication, line mapping and the review event. Everything the pipeline
// can compute is computed here, so identical findings always produce identical
// scores, order and verdicts, and the agents around them only reason.
//
// It imports the standard library only, and the workflow package imports it
// rather than the reverse: code that cannot reach the store, the forge or the
// worktree is code whose data boundary stays visible.
// Package prreview is the deterministic part of the PR review pipeline: diff
// parsing, clustering, blast radius, evidence, scoring and the review event.
package prreview
import (
@@ -123,21 +116,13 @@ const rootClusterName = "root"
const (
gitFilePrefix = "diff --git "
devNull = "/dev/null"
// oldSidePrefix and newSidePrefix are the a/ and b/ git puts in front of
// the two sides of its own diff. They are not part of the path: a finding
// anchored to "b/x" names a file the snapshot does not have. A plain
// unified diff written by another tool carries no prefix, and a path whose
// first directory really is "a" or "b" keeps it, because only its own
// side's prefix is stripped.
// Git's a/ and b/ path prefixes, stripped from their own side only.
oldSidePrefix = "a/"
newSidePrefix = "b/"
)
// gitHeaderPaths reads both paths out of a "diff --git" line, each without its
// side prefix. git writes the paths plainly, or C-quoted when one of them holds
// something it has to escape -- and a quoted line names both sides in quotes,
// because a path that needs escaping is exactly a path this line could not be
// split on a space.
// gitHeaderPaths returns both paths from a "diff --git" line, unquoted and
// without prefixes.
func gitHeaderPaths(line string) (oldPath, newPath string) {
rest := strings.TrimPrefix(line, gitFilePrefix)
if oldField, remaining, quoted := quotedField(rest); quoted {
@@ -152,11 +137,7 @@ func gitHeaderPaths(line string) (oldPath, newPath string) {
return strings.TrimPrefix(rest[:split], oldSidePrefix), strings.TrimRight(rest[split+len(" b/"):], " \r")
}
// headerPath reads the path out of a "--- " or "+++ " header: git's "b/main.go",
// a plain unified diff's path with a timestamp after a tab, a /dev/null side, or
// the C-quoted form git writes for a path it has to escape. side is the prefix
// that side of a git diff carries; it is stripped here and only here, so the
// other side's prefix survives in a path that happens to start with it.
// headerPath returns the path from a "--- " or "+++ " header, stripping side.
func headerPath(field, side string) string {
if quoted, _, ok := quotedField(field); ok {
return strings.TrimPrefix(unquotePath(quoted), side)
@@ -265,11 +246,7 @@ func parseFileType(field string) int {
// "@@" may contain anything, so nothing after it is matched.
var hunkHeaderRE = regexp.MustCompile(`^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@`)
// fileInProgress is the parser's state for the file section it is inside. The
// section's headers are read into it as facts -- which paths, what kind of
// change, which object type -- and close() turns those facts into one status,
// so the status is a statement about the section and not about the line of it
// that happened to come last.
// fileInProgress is the parser state for the current file section.
type fileInProgress struct {
change FileChange
oldPath string
@@ -314,11 +291,7 @@ func newSectionInProgress(line string) *fileInProgress {
return file
}
// note reads one of the file's own header lines: the old and new paths, the
// /dev/null side that makes a file an addition or a deletion, the rename pair,
// and the mode lines -- which say the same thing for a file whose patch has no
// hunks at all. Anything else the section says -- index, similarity -- says
// nothing about where the change is, which is all findings are positioned by.
// note records one header line of the file section.
func (f *fileInProgress) note(line string) {
switch {
case strings.HasPrefix(line, "--- "):
@@ -352,12 +325,7 @@ func (f *fileInProgress) note(line string) {
}
}
// status is what the section's own headers said the change did to the file,
// read off every fact the section stated at once. A rename wins over a mode
// change, because git reports a file that was renamed and had its mode changed
// as a rename; an addition or a deletion wins over a type change, because a
// file that was not there has no old type; and a mode change between two
// permission sets of one object type is a modification, not a typechange.
// status derives the file's change status from its headers.
func (f *fileInProgress) status() FileStatus {
switch {
case f.renamed:
@@ -415,13 +383,8 @@ func headerPair(lines []string, index int) bool {
return index+1 < len(lines) && strings.HasPrefix(lines[index+1], "+++ ")
}
// opensNextFile reports whether the header pair at index begins the next file
// rather than being body text of this one. A pair is body text -- a removed
// line whose text begins "-- " followed by an added line whose text begins
// "++ " -- while the open hunk is still waiting for the lines its header
// counted; and a section has read its own "+++ " line before a pair can be
// another file's, because the pair of the section being opened is its own
// header.
// opensNextFile reports whether the header pair at index starts the next
// file rather than being hunk content.
func (f *fileInProgress) opensNextFile(lines []string, index int) bool {
return f.headerSeen && !f.hunkOpen() && headerPair(lines, index)
}
@@ -474,11 +437,7 @@ func (f *fileInProgress) close() FileChange {
return change
}
// ParseDiff parses a unified diff into per-file changes: the file sections
// "diff --git" opens, the sections a "--- "/"+++ " header pair opens in a diff
// that has no such line, their rename, mode and /dev/null headers, and the
// hunks that carry the change. It is the one parser: every position, count and
// path this package reports is read here.
// ParseDiff parses a unified diff into per-file changes.
func ParseDiff(diff string) []FileChange {
var (
files []FileChange
@@ -13,11 +13,9 @@ type Dimension struct {
Priority float64
}
// MergeDimensions drops duplicate dimension names across the lenses' outputs
// (keeping the higher-priority copy), sorts by priority, and cuts the tail at
// cap. Order is stable for equal priority: the input order of the first lens
// that produced the name wins, so re-running the same lenses in the same
// order always keeps the same dimensions.
// MergeDimensions deduplicates dimensions by name, keeping the higher
// priority, sorts by priority and keeps the first limit. Ties keep input
// order.
func MergeDimensions(lensOutputs [][]Dimension, limit int) []Dimension {
byName := make(map[string]Dimension)
order := make([]string, 0)
+1 -5
View File
@@ -7,11 +7,7 @@ import (
"github.com/samcharles93/archie-core/internal/domain/workflow/task"
)
// Key is a scored finding's stable identity inside one gate document: file,
// line and title. Findings carry no ID, so this is what an operator's
// selection names and what filtering matches on. The document stores the key
// beside the finding (task.ReviewGateFinding), because the operator surface
// never sees this type.
// Key identifies a scored finding by file, line and title.
func (f ScoredFinding) Key() string {
return fmt.Sprintf("%s:%d:%s", f.File, f.LineStart, f.Title)
}
+10 -34
View File
@@ -136,14 +136,8 @@ type ScoreInputs struct {
BlastRadiusFiles int
}
// Score drops the findings under their severity's confidence floor, scores
// what is left, merges the duplicates among the survivors and ranks the rest by
// score. The same findings always produce the same scores and the same order,
// whatever order they were handed in.
//
// The floor comes before the merge, so a discarded finding cannot shadow a kept
// one, and the merge is a clustering rather than a scan, so a chain of
// overlapping findings collapses the same way however it was listed.
// Score drops findings below their severity's confidence floor, scores and
// merges the rest, and ranks them. The result is deterministic.
func Score(findings []Finding, inputs ScoreInputs) []ScoredFinding {
scored := make([]ScoredFinding, 0, len(findings))
for _, finding := range findings {
@@ -202,17 +196,9 @@ func sameKey(a, b ScoredFinding) bool {
return a.File == b.File && a.Category == b.Category
}
// mergeRun unions the overlapping ranges of one (file, category) group into
// clusters. The group arrives ordered by line, so a cluster is a run of members
// whose start is inside the range the run has already covered -- which is what
// makes the overlap transitive: 1-2, 2-3 and 3-4 are one cluster even though
// 1-2 and 3-4 do not touch. A run that begins where the previous one ended is
// two clusters: line 13 and the range 10-12 are two places.
//
// The cluster contributes the highest-scoring member, because that is the one
// that says the most, over the union of the cluster's lines, because the
// cluster is the claim and it covers every line of it. It is blocking when any
// member is: a merge may discard wording, never a verdict.
// mergeRun merges overlapping line ranges in one (file, category) group,
// keeping the best-scoring member over the union of lines. Blocking if any
// member is.
func mergeRun(group []ScoredFinding) []ScoredFinding {
clusters := make([]findingCluster, 0, len(group))
for _, member := range group {
@@ -230,11 +216,7 @@ func mergeRun(group []ScoredFinding) []ScoredFinding {
return merged
}
// findingCluster is the run of overlapping findings one output finding stands
// for: the best member's wording and score, the union of the members' lines,
// and the disjunction of their verdicts. The best member is kept whole, so
// choosing between two members reads the fields they carry and never the
// cluster's widened range.
// findingCluster is a run of overlapping findings.
type findingCluster struct {
best ScoredFinding
first int
@@ -384,11 +366,8 @@ var severityAliases = map[Severity]Severity{
Severity("trivial"): SeverityNitpick,
}
// normalizeSeverity reads a severity as one of the rubric's four words, however
// it is spelled or capitalised. A word the rubric does not know is read as a
// suggestion: the lowest weight that keeps a plausible finding in the review
// rather than the highest, because an unrecognised word is not evidence of
// severity.
// normalizeSeverity maps a severity to one of the four rubric words;
// unknown words become suggestion.
func normalizeSeverity(severity Severity) Severity {
lowered := Severity(strings.ToLower(strings.TrimSpace(string(severity))))
switch lowered {
@@ -426,11 +405,8 @@ func IsHighPriority(f Finding) bool {
}
}
// ReviewEventFor decides the event a review is submitted with: a blocking
// finding requests changes, and anything else -- including a review that found
// nothing -- is a comment. A pipeline that found nothing has said nothing about
// the change, and an approval from a reviewer that did not look is worse than
// silence.
// ReviewEventFor returns REQUEST_CHANGES when any finding blocks, else
// COMMENT. It never approves.
func ReviewEventFor(findings []ScoredFinding) ReviewEvent {
for _, finding := range findings {
if finding.Blocking {
+3 -10
View File
@@ -2,17 +2,10 @@ package task
import "context"
// Caller is what a workflow.call step uses to start a callee run and read it
// back while waiting. It is the consumer-owned contract the workflow engine
// holds (the same shape as Store), satisfied by *staterpc.Client for an
// agent-container run: the callee is a first-class task the State Store
// derives from the caller's row.
// Caller starts a workflow.call callee and reads it back.
type Caller interface {
// StartCall enqueues the callee task for callerTaskID's workflow.call
// step: org, workspace, identity, owner, repo and issue number are
// derived from the caller's row, the callee carries the call's inputs,
// and the callee's depth is the caller's + 1. The store refuses a
// caller that is not running and a call past the depth limit.
// StartCall enqueues the callee for callerTaskID's call step at depth + 1.
// It fails if the caller is not running or the depth limit is exceeded.
StartCall(ctx context.Context, callerTaskID int64, workflow string, inputs map[string]any) (*Task, error)
// CallStatus reads one call's callee: its status, latest transition detail
// and written outputs. A store only answers for a task whose
+3 -16
View File
@@ -1,16 +1,6 @@
package task
// ChangeStats is the change one attempt produced, measured at the moment it
// was committed or pushed.
//
// It is a measurement, not a view: the worktree it was read from is deleted on
// merge, close and no-PR terminal states, and a retry resets the branch onto
// its base, so this is the only record of what an attempt actually changed.
// Nothing re-derives it after the fact.
//
// The value types live in this subpackage because package workflow must not
// import internal/worktree. Both the workflow engine and persistence boundary
// can use the measurement without depending on git infrastructure.
// ChangeStats is what one attempt changed, measured at commit or push time.
type ChangeStats struct {
BaseSHA string `json:"base_sha"`
HeadSHA string `json:"head_sha"`
@@ -53,9 +43,6 @@ const (
ChangeTypeChanged = "typechange"
)
// MaxCapturedFiles caps how many file entries one capture persists. Unlike
// Event.Detail, an event's data is not length-limited by the store, so this cap
// is what keeps one large refactor from writing an unbounded payload. A capture
// that dropped entries keeps the totals of the full set and reports itself as
// truncated.
// MaxCapturedFiles caps the file entries one capture stores; totals still
// cover all files.
const MaxCapturedFiles = 200
@@ -1,12 +1,7 @@
package task
// WorkflowDefinitionEntry is one workflow's portable YAML as the control plane
// stores and serves it. YAML stays canonical and can be copied between Archie
// installations.
//
// It lives with the task vocabulary rather than with the engine for the same
// reason Definition does: a dashboard reads the stored collection without
// linking the workflow engine, which the UI process must never pull in.
// WorkflowDefinitionEntry is one workflow's YAML as stored in the control
// plane.
type WorkflowDefinitionEntry struct {
ID string `json:"id"`
YAML string `json:"yaml"`
+3 -11
View File
@@ -62,11 +62,7 @@ type WorkflowInterface struct {
DeclaredNeeds WorkflowNeeds `yaml:"needs" json:"needs"`
}
// Needs reports the harness requirements the interface carries: the declared
// needs, plus the captures a declared output forces, because an output is
// written through a capture tool. Profile selection reads this rather than
// DeclaredNeeds, so a workflow that declares outputs cannot name a Kit profile
// whose harness serves no capture tools.
// Needs returns the declared needs plus captures when outputs are declared.
func (w WorkflowInterface) Needs() WorkflowNeeds {
needs := w.DeclaredNeeds
if len(w.Outputs) > 0 {
@@ -160,12 +156,8 @@ func (w WorkflowInterface) CheckInputs(values map[string]any) error {
return nil
}
// CheckOutputs rejects declared-output values that do not satisfy the
// declared outputs: the same rules CheckInputs applies to inputs (required,
// undeclared, wrong type), read from the other side of the interface.
// A written null
// counts as not written, as CheckInputs treats a null input; an unwritten
// optional output leaves its key absent rather than null.
// CheckOutputs validates output values against the declared outputs. Null
// counts as not written.
func (w WorkflowInterface) CheckOutputs(values map[string]any) error {
for name, spec := range w.Outputs {
v, ok := values[name]
+2 -16
View File
@@ -6,22 +6,8 @@ import (
"github.com/samcharles93/archie-core/internal/taskstate"
)
// ReviewGate is the operator-approval gate's whole conversation with the
// operator, encoded on the task's review_gate column
//
// It lives with the task record it encodes, the way EncodeInputs does, for the
// same reason: the dashboard process renders and answers a gate, and it must
// not link the workflow engine that owns the finding type the pipeline reads.
// The findings therefore cross this document as opaque JSON beside the key an
// operator's selection names (ReviewGateFinding); only the pipeline decodes
// them.
//
// The offer half -- the findings, the head SHA, the pull request's identity
// and the workflow the wait resumes -- is written by the gate stage before it
// ends the run in waiting_human. The answer half -- the outcome, the finding
// keys an approve posts and the instructions a re-review carries -- is
// written back by the response path in the guarded requeue that clears the
// wait.
// ReviewGate is the operator-approval gate document stored on the task: the
// offered findings and context, and the operator's answer.
type ReviewGate struct {
// Findings is the review the operator is answering. An approve keeps it
// (the resumed run posts it, filtered by Selection); a re-review's
+1 -5
View File
@@ -40,11 +40,7 @@ type StepStart struct {
ParentID int64
Kind string
Name string
// CalledExecutionID names the WorkflowExecution a `call` step started.
// The store refuses a value that is not the caller's own callee (the
// callee's call_parent_task_id must name this execution), so a step's
// tree cannot cross runs: a cancel of that execution would otherwise
// cancel work the caller never started. Non-call kinds leave it 0.
// CalledExecutionID is the execution a call step started; 0 for other kinds.
CalledExecutionID int64
}
+17 -70
View File
@@ -1,10 +1,5 @@
// Package task is the task-execution vocabulary of the workflow domain:
// the Task record, its lifecycle statuses, and the narrow Store contract
// workflow stages call mid-run. It split out of package workflow
// so the UI process can hold the vocabulary without
// linking the pipeline engine there -- which drags in agentexec, skill and
// tools. package workflow keeps aliases, so daemon-side callers are
// unaffected.
// Package task defines the Task record, its statuses and the Store contract
// workflow stages use.
package task
import (
@@ -66,13 +61,8 @@ type Task struct {
// (parking-to-queued transitions). When it reaches the configured
// max_retries the daemon moves the task to StatusDead.
RetryCount int `json:"retry_count"`
// RetryMode is the operator's worktree choice for the next dispatch of this
// task (taskstate.RetryMode): refresh onto the base branch, or continue the
// work already pushed on Branch. The retry action writes it -- and the
// reaction consumer writes continue when it queues a remediation -- and the
// daemon's prepareWorkspace reads it to position the worktree. Empty reads
// as the explicit default, RefreshOntoBase; it is never inferred from the
// workflow at dispatch.
// RetryMode is the worktree mode for the next dispatch; empty means
// RefreshOntoBase.
RetryMode string `json:"retry_mode"`
// WatchCommentID is the poll backstop's high-water mark over forge
// review-comment IDs for this task (pr-review-remediation.md decision
@@ -84,11 +74,8 @@ type Task struct {
// and comment IDs are independent forge sequences, and one combined
// cursor would silently skip reviews once a larger comment ID landed.
ReviewCursor int64 `json:"review_cursor"`
// Source is "forge" (default; a real forge issue backs this task) or
// "chat" (created via /spawn with no forge issue). Workflow stages
// and daemon reconciliation must skip forge-only operations (issue
// labels, comments, replies) for chat-sourced tasks; IssueNumber on
// a chat task is a synthetic value, not a real forge issue.
// Source is "forge" or "chat". Chat tasks have a synthetic IssueNumber and
// skip forge operations.
Source string `json:"source"`
// Identity is the archie identity that owns this task (chat-spawned
// tasks only; empty for forge-sourced tasks and single-identity
@@ -110,47 +97,22 @@ type Task struct {
// the workflow's declared inputs at dispatch. They reach the agent as
// structured data, never as body text.
Inputs map[string]any `json:"inputs,omitempty"`
// Outputs are the structured results this run wrote to the workflow's
// declared outputs. The set is
// attempt-scoped: a claim starts the next attempt with an empty set and
// the finish write replaces the row's set wholesale. Callers read these
// only from a successful terminal state, through WorkflowCallStatus.
// Outputs are this attempt's declared outputs.
Outputs map[string]any `json:"outputs,omitempty"`
// ReviewPayload is the JSON-encoded review unit (the forge review's
// actionable comments) the remediate workflow's current run must address.
// The daemon's reaction consumer injects it before queuing a remediation
// run, so the run is recoverable from the task record itself rather than
// only from a prompt. Empty outside a remediation run. RetryCount doubles
// as the remediation round counter for this same task, bounded by the
// repo's existing max_retries (decision 5's round cap).
// ReviewPayload is the JSON review unit the remediate run must address.
ReviewPayload string `json:"review_payload"`
// ParkClass is the producer-recorded answer to "what kind of
// intervention does this park need?" (taskstate.ParkClass). Set at the
// park site, never inferred from reason text; needs_human is the
// default an unclassified park reads as.
ParkClass string `json:"park_class"`
// RemediationRounds counts review-triggered remediation rounds,
// bounded by the repo's max_retries (pr-review-remediation.md
// decision 5). Deliberately separate from RetryCount, the operator
// budget: one shared counter made N operator retries eat the
// review-remediation budget and vice versa.
// RemediationRounds counts review-triggered remediation rounds.
RemediationRounds int `json:"remediation_rounds"`
// ReviewGate is the operator-approval gate's whole conversation with the
// operator, persisted as one JSON document (prreview.EncodeReviewGate): the
// offer the gate writes before it waits for an operator -- the scored
// findings, the head SHA, the pull request's identity and the workflow the
// wait resumes -- and the answer the response path fills in -- the outcome,
// the selected findings' keys for an approve and the instructions for a
// re-review. Without it, "post the selected findings" cannot mean the
// findings the operator saw: the resumed run recomputes them with agent
// calls. Empty for a task that never reached the gate.
// ReviewGate is the encoded review gate document; empty if the task never
// reached the gate.
ReviewGate string `json:"review_gate"`
// RereviewRounds counts how many operator re-reviews the pr-review gate
// granted, incremented in the same guarded write that requeues the
// re-review and capped at prreview.MaxRereviewRounds.
// Deliberately
// separate from both RetryCount and RemediationRounds -- one shared
// counter made unrelated retries draw another phase's budget down.
// RereviewRounds counts operator re-reviews, capped at
// prreview.MaxRereviewRounds.
RereviewRounds int `json:"rereview_rounds"`
// CallParentTaskID is the task whose workflow.call step started this
// one; 0 on a root run. A caller reads only the tasks it started,
@@ -182,14 +144,7 @@ func (t Task) IsForgeBacked() bool {
return t.Source != SourceChat
}
// EffectivePRNumber resolves the pull request a pr-review task targets:
// PRNumber when a producer already set it directly (archie's own PRs, which
// never goes through binding/chat input assignment), otherwise the pr_number
// input a binding (watched repositories) or a chat task (the operator
// trigger) assigned generically through Inputs. Returns 0 when neither is
// set. DecodeInputs (the store's round-trip) decodes a JSON number as
// json.Number; a caller that built Inputs by hand in Go may use float64 or
// int instead, so all three are accepted.
// EffectivePRNumber returns PRNumber, else the pr_number input, else 0.
func (t Task) EffectivePRNumber() int {
if t.PRNumber != 0 {
return t.PRNumber
@@ -218,12 +173,8 @@ type Store interface {
Update(ctx context.Context, t *Task) error
Transition(ctx context.Context, taskID int64, from, to, detail string) error
InsertEvent(ctx context.Context, e events.Event) (int64, error)
// StartStep records a StepExecution entering running:
// the store creates the row,
// enforces the step transition table and the execution's own status, and
// writes the transition's stage_start event in the same transaction. It
// returns the step's id and the persisted event, which the caller publishes
// to its bus after the write commits.
// StartStep records a step entering running and returns its id and the
// persisted event.
StartStep(ctx context.Context, s StepStart) (int64, events.Event, error)
// FinishStep moves one step to its outcome under the same table, writing
// the stage_finish event in the same transaction, and returns that event
@@ -231,11 +182,7 @@ type Store interface {
FinishStep(ctx context.Context, s StepFinish) (events.Event, error)
}
// Definition is the operator-safe snapshot of an executable workflow. It
// contains only identity and stage order, never executable function values.
// It lives with the task vocabulary (not with the engine in package
// workflow) for the same reason this package exists: dashboards render
// Definitions without linking the engine.
// Definition is a workflow's id and stage order.
type Definition struct {
ID string `json:"id"`
Name string `json:"name"`
+1 -5
View File
@@ -7,11 +7,7 @@ import (
"github.com/jackc/pgx/v5/pgconn"
)
// clip limits s to n bytes without splitting a UTF-8 rune. It is the exact
// write-side normalisation the SQLite store applied before inserting event
// detail, transition detail, park reasons and review payloads: a generated
// query that drops it lets an oversized value through where the old store
// truncated it.
// clip limits s to n bytes without splitting a UTF-8 rune.
func clip(s string, n int) string {
if len(s) <= n {
return s
@@ -73,11 +73,8 @@ func (s *EDA) PutHarnessSecret(ctx context.Context, secret harnesssecret.Secret)
return nil
}
// sealHarnessSecret JSON-marshals the token set and encrypts it under
// bindingcipher.HarnessSecretDomain -- its own domain separator, distinct
// from BindingDomain's, so a row cannot be relocated between the two tables
// and still authenticate. OAuth tokens require a configured encryption key;
// the binding store's legacy plaintext fallback does not apply here.
// sealHarnessSecret encrypts the token set under HarnessSecretDomain. An
// encryption key is required.
func (s *EDA) sealHarnessSecret(payload harnessSecretPayload) (string, error) {
if s.cipher == nil {
return "", errors.New("postgres: harness secrets require an encryption key")
@@ -230,12 +230,9 @@ func (s *Store) BindSubject(ctx context.Context, id identity.IdentityID, subject
return tx.Commit(ctx)
}
// BootstrapIdentities seeds the system identity and the configured legacy
// names idempotently, migrating any forge tasks that still carry a legacy
// name to the stable id. Each legacy name is derived through
// identity.FromLegacyName, so a name this store cannot turn into an identity is
// reported rather than silently skipped -- the file loader refuses the same
// names (configuration.validateIdentities).
// BootstrapIdentities seeds the system identity and the legacy names, and
// moves tasks carrying a legacy name to its stable id. Invalid names are
// errors.
func (s *Store) BootstrapIdentities(ctx context.Context, legacyNames []string) error {
values := make([]identity.Identity, 0, len(legacyNames)+1)
values = append(values, identity.System())
@@ -89,11 +89,8 @@ func AcquireAll(ctx context.Context, pool *pgxpool.Pool, names []string) (releas
return release, nil
}
// Backup writes a whole-database pg_dump archive to out. It takes no claim:
// pg_dump reads one consistent snapshot, so it is safe against serving
// processes, which is what the update installer needs. The archive goes to a
// scratch file and replaces out only once pg_restore can read it back, so a
// failed run never costs the previous good snapshot.
// Backup writes a pg_dump archive to out, replacing it only once pg_restore
// can read the new archive.
func Backup(ctx context.Context, databaseURL, out string) error {
tmp, err := os.CreateTemp(filepath.Dir(out), filepath.Base(out)+".tmp*")
if err != nil {
@@ -134,14 +131,9 @@ func ValidateSnapshot(ctx context.Context, path string) ([]string, error) {
return tables, nil
}
// Restore replaces the whole database with the snapshot at from. It is
// destructive: every write after the snapshot is lost. It refuses unless it
// can claim every service role, so no serving process is running and none can
// start until it finishes; a claim that cannot be checked is a refusal too.
//
// pg_restore --clean drops only what the archive holds, so tables a later
// migration created are dropped first; otherwise they would survive into the
// restored schema and break the next upgrade's migration.
// Restore replaces the whole database with the snapshot at from. It refuses
// unless it can claim every service role. Tables the archive lacks are
// dropped first.
func Restore(ctx context.Context, databaseURL, from string) error {
tables, err := ValidateSnapshot(ctx, from)
if err != nil {
+1 -12
View File
@@ -1,11 +1,3 @@
// Orgs, workspaces, memberships and agent assignments: the Postgres
// implementation of internal/domain/org's contracts, plus the resumable
// default org/workspace upgrade the State Store runs at boot
//
// The upgrade refuses nothing itself; the refusal to serve scoped calls
// until it has finished is enforced by the boot order -- the State Store
// runs this upgrade before its gRPC listener starts, and a failed upgrade
// fails the boot (fail closed) rather than serving records with no org.
package postgres
import (
@@ -244,10 +236,7 @@ func (s *Store) UpgradeDefaultOrg(ctx context.Context) error {
}
// runUpgradePhase stamps one phase's tables and records its ledger row in one
// transaction, after making sure the default org and workspace exist and
// every agent identity belongs to the default org. An interrupted phase
// leaves no ledger row, so the next start re-runs it from the beginning --
// every stamp is idempotent on rows the upgrade has not covered yet.
// transaction. An interrupted phase reruns from the start.
func (s *Store) runUpgradePhase(ctx context.Context, name string, stamps []func(context.Context, *postgresdb.Queries) (int64, error)) error {
tx, err := s.pool.Begin(ctx)
if err != nil {
+4 -18
View File
@@ -96,17 +96,8 @@ func (s *Resources) Audit(ctx context.Context, table string, keys []string, limi
return entries, nil
}
// PutResource applies one control-plane resource write.
//
// It is idempotent per request ID: a write whose (org_id, kind, request_id) is already
// in resource_history returns that revision instead of writing a second one, so a
// retry that reached the store twice is still one revision. The ledger is what
// carries the key -- resource_history outlives the row it describes -- so a
// replay of a revision whose resource an operator removed re-creates that row
// rather than answering with a revision the store no longer holds. The
// alternative is a write that reports a version for a kind that is absent: the
// caller cannot tell the difference, and a kind can stay gone while every
// process believes it holds a value.
// PutResource applies one control-plane resource write, idempotent per
// request ID.
func (s *Resources) PutResource(ctx context.Context, write storecontract.ResourceWrite) (_ storecontract.Resource, retErr error) {
if err := checkResourceKey(write.OrgID, write.Kind); err != nil {
return storecontract.Resource{}, err
@@ -197,13 +188,8 @@ func appendResourceRevision(ctx context.Context, queries *postgresdb.Queries, wr
return history, nil
}
// replayedResource answers a write whose request ID resource_history already
// holds. The ledger's revision is the answer and a replay writes nothing, with
// one repair: when the resource that revision describes is no longer the current
// row, the row is re-created from it. That is the state an operator removing a
// resource leaves behind, and without the repair the store answers with a
// revision it does not hold, so the caller reads a version for a kind that is
// absent and the kind stays absent.
// replayedResource answers a repeated request ID with its recorded revision,
// re-creating the row if it was removed since.
func (s *Resources) replayedResource(ctx context.Context, queries *postgresdb.Queries, tx pgx.Tx, existing postgresdb.ResourceByRequestRow) (storecontract.Resource, error) {
if _, err := queries.ResourceByKind(ctx, postgresdb.ResourceByKindParams{OrgID: existing.OrgID, Kind: existing.Kind}); errors.Is(err, pgx.ErrNoRows) {
if _, err := queries.ReinsertResource(ctx, postgresdb.ReinsertResourceParams{
+13 -36
View File
@@ -20,12 +20,8 @@ import (
// bus after the write commits, and the daemon's event sink skips
// already-persisted rows by their assigned ID -- the EmitDurable convention.
// StartStep records a StepExecution entering running: the row is created
// pending, guarded into running under the shared step transition table, and
// the stage_start event is appended in the same transaction. The execution's
// row is locked for the whole write, so its status check cannot race the
// guarded updates, and org and workspace are stamped from it -- the request's
// ownership fields are ignored, like every owned record.
// StartStep creates a step and moves it to running, appending stage_start in
// the same transaction. Org and workspace come from the execution row.
func (s *Store) StartStep(ctx context.Context, start task.StepStart) (int64, events.Event, error) {
if !task.ValidStepKind(start.Kind) {
return 0, events.Event{}, fmt.Errorf("%w: unknown step kind %q", storecontract.ErrInvalidStep, start.Kind)
@@ -98,11 +94,8 @@ func (s *Store) StartStep(ctx context.Context, start task.StepStart) (int64, eve
return stepID, event, nil
}
// verifyCallStep refuses a call step whose callee is not this run's own:
// the callee's call_parent_task_id must name the recording execution, or the
// call step cannot record (a missing callee is the caller's stale view).
// Without this check a cancel of the recording run would sweep work it never
// started.
// verifyCallStep refuses a call step whose callee is not this execution's
// own.
func (s *Store) verifyCallStep(ctx context.Context, q *postgresdb.Queries, start task.StepStart) error {
if start.CalledExecutionID == 0 {
return nil
@@ -151,11 +144,9 @@ type stepParentState struct {
underTerminal bool
}
// FinishStep moves one step to its outcome under the shared step transition
// table, writing the stage_finish event in the same transaction and returning
// it for the caller's post-commit publish. A step that is missing, that is
// not the named execution's, or whose status does not match from is stale; an
// off-table from->to pair is refused as an illegal transition.
// FinishStep moves a step to its outcome and returns the stage_finish event.
// A missing, foreign or mismatched step is stale; a disallowed pair is
// illegal.
func (s *Store) FinishStep(ctx context.Context, finish task.StepFinish) (events.Event, error) {
tx, err := s.pool.Begin(ctx)
if err != nil {
@@ -245,12 +236,8 @@ func stepEventData(to taskstate.StepStatus, durationMS int64, detail string) map
return data
}
// ListSteps reads one execution's recorded steps, every attempt oldest first
// when attempt is 0, or just the one it names. It is the dashboard run
// detail's authoritative source,
// replacing the fold over stage_start/stage_finish events tasks.stage used to
// back -- unlike StartStep/FinishStep, this is a plain read with no
// transition to guard, so it takes no transaction.
// ListSteps returns an execution's steps, for every attempt when attempt is
// 0.
func (s *Store) ListSteps(ctx context.Context, executionID int64, attempt int) ([]task.StepExecution, error) {
rows, err := s.queries().ListStepExecutions(ctx, postgresdb.ListStepExecutionsParams{
ExecutionID: executionID, Attempt: int64(attempt),
@@ -287,14 +274,8 @@ func stepParentID(parentID int64) pgtype.Int8 {
return pgtype.Int8{Int64: parentID, Valid: parentID != 0}
}
// CancelExecution is the one cancel path: one transaction moves every
// non-terminal StepExecution of the execution's current attempt to cancelled --
// one event row each -- and the execution itself to the status the operator
// action names, under the shared execution transition table. Staleness is
// decided before legality, as guardTransition decides it, and the audit row
// lands in the same write. The caller cancels the in-memory context after this
// commits; the worker's next step write then fails ErrStaleTransition and
// stops.
// CancelExecution cancels the current attempt's open steps and moves the
// execution to `to`, in one transaction with events and an audit row.
func (s *Store) CancelExecution(ctx context.Context, taskID int64, reason, to string) ([]int64, error) {
tx, err := s.pool.Begin(ctx)
if err != nil {
@@ -367,12 +348,8 @@ func (s *Store) CancelExecution(ctx context.Context, taskID int64, reason, to st
return ids, nil
}
// cancelWaitedCallees cancels each callee the caller was still waiting on
// through its own CancelExecution, under its own lifecycle, in the caller's
// write's aftermath -- the callee's own steps and its own move to the same
// destination. A chain of calls is bounded by the call depth the enqueue
// enforces, so the recursion is finite; a callee that cannot be cancelled is
// reported, and the caller's own record stands either way.
// cancelWaitedCallees cancels each callee the caller was waiting on.
// Failures are reported; the caller's cancel stands.
func (s *Store) cancelWaitedCallees(ctx context.Context, waiting []postgresdb.WaitingCallStepsRow, reason, to string) error {
var failures []error
for _, call := range waiting {
+20 -57
View File
@@ -18,11 +18,8 @@ import (
"github.com/samcharles93/archie-core/internal/taskstate"
)
// Store is the PostgreSQL implementation of the State Store. It carries the
// full task/event/identity/status surface behind the storecontract interfaces,
// with the control-plane resource surface embedded from Resources. The pool is
// process-scoped and owned by the composition (internal/app/archied), not by
// the Store, so Close is a no-op.
// Store is the PostgreSQL State Store. The pool belongs to the caller, so
// Close is a no-op.
type Store struct {
pool *pgxpool.Pool
*Resources
@@ -37,16 +34,9 @@ func (s *Store) queries() *postgresdb.Queries {
return postgresdb.New(s.pool)
}
// guardTransition locks the task's row and checks the status write the caller
// is about to perform: a row whose status is not the expected from is stale
// (ErrStaleTransition), a from->to pair outside the shared transition table is
// refused with ErrIllegalTransition.
// Staleness is decided first, so
// a caller that is wrong about the row's state gets the stale sentinel even
// when its pair is also unroutable. The row stays locked for the caller's
// transaction, so the checks cannot race the guarded write that follows.
// A missing row is stale, matching what the guarded update alone used to
// return.
// guardTransition locks the task row and checks the transition: a status
// other than from is ErrStaleTransition, a disallowed pair is
// ErrIllegalTransition. A missing row is stale.
func guardTransition(ctx context.Context, q *postgresdb.Queries, taskID int64, from, to string) error {
status, err := q.LockTaskStatus(ctx, taskID)
if errors.Is(err, pgx.ErrNoRows) {
@@ -74,11 +64,8 @@ func (s *Store) Close() error { return nil }
// JSON-safe floor that keeps synthetic issue numbers clear of real ones.
const syntheticIssueNumberBase = 1_000_000_000_000_000
// structuredPayloadBytes is the write-side bound the store applies to a
// structured payload (review_payload today, task outputs now). A value that
// would exceed it is refused for outputs -- clipped JSON does not parse, and a
// caller must receive an object or nothing -- where the legacy review payload
// is still clipped.
// structuredPayloadBytes bounds structured payloads. Oversized outputs are
// refused; review payloads are clipped.
const structuredPayloadBytes = 4000
// taskFromRow maps the generated task row to the workflow.Task the daemon and
@@ -159,11 +146,8 @@ func (s *Store) EnqueueIssue(ctx context.Context, owner, repo string, number int
return n > 0, nil
}
// EnqueueChatTask inserts a queued chat-sourced task and returns the full row.
// The store allocates the synthetic issue number durably so processes sharing
// the database cannot generate the same value. inputs are the task's workflow
// inputs (the operator trigger's pr_number, for instance); a chat task carries
// no binding provenance, so the insert is the only writer of that column.
// EnqueueChatTask inserts a queued chat task with a store-allocated synthetic
// issue number.
func (s *Store) EnqueueChatTask(ctx context.Context, owner, repo, title, body, wf, identity string, inputs map[string]any) (*workflow.Task, error) {
encoded, err := task.EncodeInputs(inputs)
if err != nil {
@@ -226,11 +210,8 @@ func (s *Store) ClaimByIssue(ctx context.Context, owner, repo string, number int
return taskFromRow(t), nil
}
// Transition moves a task to a new status and records the audit detail. The
// from status guards the update; a mismatch returns ErrStaleTransition without
// writing an audit row, and a from->to pair outside the shared transition
// table returns ErrIllegalTransition. Transitioning to parked also stores
// detail as ParkReason in the same transaction.
// Transition moves a task from `from` to `to` with an audit row. Parking
// also stores detail as ParkReason.
func (s *Store) Transition(ctx context.Context, taskID int64, from, to, detail string) error {
tx, err := s.pool.Begin(ctx)
if err != nil {
@@ -295,11 +276,7 @@ func (s *Store) ParkTask(ctx context.Context, taskID int64, from, detail, class
// Update persists mutable task fields written by workflows.
func (s *Store) Update(ctx context.Context, t *workflow.Task) error {
// The row write is where a run's outputs land.
// An encoded set past the bound the store applies to a structured payload
// is refused rather than clipped: clipped JSON does not parse, and a caller
// would receive a broken object as a value. The engine turns the refusal
// into a park, so nothing silently loses its structured result.
// Oversized outputs are refused, not clipped.
outputs, err := task.EncodeOutputs(t.Outputs)
if err != nil {
return fmt.Errorf("store: encode task %d outputs: %w", t.ID, err)
@@ -414,12 +391,8 @@ func (s *Store) RetryTask(ctx context.Context, taskID int64, fromStatus, wf, ret
})
}
// RespondReviewGate is the review gate response write:
// one guarded
// requeue that records the operator's answer, increments rereview_rounds for
// a re-review only, and writes one audit row -- all in one transaction. The
// cap is checked under the row lock the transition guard takes, so two
// simultaneous re-reviews cannot both spend the last round.
// RespondReviewGate records the operator's gate answer and requeues, counting
// re-reviews against the cap under the row lock.
func (s *Store) RespondReviewGate(ctx context.Context, taskID int64, fromStatus, gate string, rereview bool, maxRounds int) error {
tx, err := s.pool.Begin(ctx)
if err != nil {
@@ -520,11 +493,8 @@ func (s *Store) ArchiveTask(ctx context.Context, taskID int64, fromStatus string
return eventID, nil
}
// RecoverStale re-queues tasks left running by a crashed or replaced daemon
// and, in the same transaction, moves the steps those executions left running
// to the step transition table's interrupted outcome: one event row per step
// transition and the execution's audit row land in the same write. The next
// attempt starts with fresh steps; earlier attempts are never rewritten.
// RecoverStale requeues tasks left running and marks their running steps
// interrupted, in one transaction.
func (s *Store) RecoverStale(ctx context.Context) (int64, error) {
tx, err := s.pool.Begin(ctx)
if err != nil {
@@ -671,12 +641,9 @@ func (s *Store) TaskByID(ctx context.Context, taskID int64) (*workflow.Task, err
return taskFromRow(t), nil
}
// StartCall enqueues the callee of callerTaskID's workflow.call step.
// The store owns the table, so it re-checks
// both runtime invariants the engine checks: the caller must be running and
// the call must not pass workflow.MaxCallDepth. The callee inherits the
// caller's org, workspace, identity, owner and repo, and takes a fresh
// synthetic issue number, the same allocator chat tasks use.
// StartCall enqueues a workflow.call callee inheriting the caller's org,
// workspace, identity and repo. The caller must be running and within
// workflow.MaxCallDepth.
func (s *Store) StartCall(ctx context.Context, callerTaskID int64, wf string, inputs map[string]any) (*workflow.Task, error) {
encoded, err := task.EncodeInputs(inputs)
if err != nil {
@@ -703,11 +670,7 @@ func (s *Store) StartCall(ctx context.Context, callerTaskID int64, wf string, in
return taskFromRow(callee), nil
}
// callRefusal names why EnqueueCallTask inserted nothing. The three refusals
// are distinct failures an operator reads differently: a missing caller is a
// problem, a caller that is not running is a stale retry, and a depth
// refusal is the limit doing its job. The two behavioural ones carry the
// caller's detail in the log and the sentinel across the wire.
// callRefusal explains why EnqueueCallTask inserted nothing.
func (s *Store) callRefusal(ctx context.Context, callerTaskID int64) error {
caller, err := s.queries().TaskByID(ctx, callerTaskID)
if errors.Is(err, pgx.ErrNoRows) {
+11 -34
View File
@@ -13,11 +13,7 @@ import (
// protocolVersion is the MCP protocol version this client speaks.
const protocolVersion = "2024-11-05"
// Transport is the narrow interface Client depends on -- satisfied by
// [*StdioTransport]. Tests substitute a fake to avoid spawning a real
// subprocess. Notify is separate from Send because a notification (no
// "id") never gets a JSON-RPC response -- a transport whose Send always
// waits for a correlated reply would hang forever if asked to send one.
// Transport sends requests and notifications to an MCP server.
type Transport interface {
Send(ctx context.Context, body []byte) ([]byte, error)
Notify(ctx context.Context, body []byte) error
@@ -31,11 +27,7 @@ type Client struct {
transport Transport
serverName string
nextID atomic.Int64
// callMu serializes tools/call requests to this server. Most MCP
// servers are single-threaded processes and don't expect or handle
// concurrent requests safely, so serializing is the default. A server
// whose config declares it handles concurrent requests gets no callMu:
// nil means this server's calls are never held apart.
// callMu serializes tools/call to this server. Nil allows concurrent calls.
callMu *sync.Mutex
// samplingHandler answers server-initiated sampling/createMessage
// requests. Set once at construction, so reading it from a transport
@@ -54,15 +46,9 @@ func WithSamplingHandler(handler SamplingHandler) ClientOption {
return func(c *Client) { c.samplingHandler = handler }
}
// NewClient builds a Client over transport. serverName identifies this
// MCP server in log/error messages; it need not match the server's own
// self-reported name. parallelToolCalls drops the per-server serialization
// of tools/call: false (the default) keeps one call in flight at a time,
// true lets the caller's own concurrency through.
//
// A transport that can receive server-initiated requests gets this client
// registered as their handler; one that cannot (the stateless HTTP
// transport) has no server→client channel for them to arrive on.
// NewClient builds a Client over transport. parallelToolCalls allows
// concurrent tools/call. The client handles server-initiated requests when
// the transport supports them.
func NewClient(transport Transport, serverName string, parallelToolCalls bool, opts ...ClientOption) *Client {
c := &Client{transport: transport, serverName: serverName}
if !parallelToolCalls {
@@ -77,11 +63,8 @@ func NewClient(transport Transport, serverName string, parallelToolCalls bool, o
return c
}
// handleServerRequest dispatches one server-initiated request. The MCP spec
// defines sampling/createMessage as the request a server sends to a client;
// everything else is method-not-found. A request this client cannot answer
// always gets an explicit JSON-RPC error response -- dropping it would leave
// the server blocked on a reply that never comes.
// handleServerRequest answers sampling/createMessage and returns
// method-not-found for anything else.
func (c *Client) handleServerRequest(ctx context.Context, method string, params json.RawMessage) (json.RawMessage, *ErrorData) {
if method != "sampling/createMessage" {
return nil, &ErrorData{Code: ErrCodeMethodNotFound, Message: "method not found: " + method}
@@ -156,11 +139,8 @@ type ResourceContent struct {
Blob string `json:"blob,omitempty"`
}
// CallToolResult is the result of tools/call. IsError reports a
// tool-level failure (the call reached the tool, which then failed) as
// distinct from a transport or JSON-RPC protocol error -- the MCP spec
// requires tool failures to be reported this way so the calling LLM sees
// the failure content instead of a bare error.
// CallToolResult is a tools/call result. IsError reports a tool-level
// failure.
type CallToolResult struct {
Content []ContentBlock `json:"content"`
IsError bool `json:"isError,omitempty"`
@@ -212,11 +192,8 @@ func (c *Client) ListTools(ctx context.Context) ([]ToolSchema, error) {
}
}
// CallTool invokes a tool by name with the given arguments. A non-nil
// error means the call could not be completed at all (transport failure,
// malformed response, unknown method). A tool that ran and failed is
// reported via CallToolResult.IsError, not a Go error -- see
// [CallToolResult].
// CallTool calls a tool. A Go error means the call failed; a tool failure is
// CallToolResult.IsError.
func (c *Client) CallTool(ctx context.Context, name string, arguments map[string]any) (CallToolResult, error) {
if c.callMu != nil {
c.callMu.Lock()
+2 -7
View File
@@ -21,13 +21,8 @@ func writeMessage(w io.Writer, data []byte) error {
return err
}
// readMessage reads one newline-delimited JSON-RPC message from r and returns
// the raw JSON bytes without its line ending.
//
// r must be a *bufio.Reader. Callers that hold a plain io.Reader should
// wrap it once with bufio.NewReader and reuse that wrapper across
// multiple readMessage calls -- creating a new bufio.Reader per call
// silently drops buffered data and breaks multi-message streams.
// readMessage reads one newline-delimited JSON-RPC message from r, which must
// be a reused *bufio.Reader.
func readMessage(r io.Reader) ([]byte, error) {
br, ok := r.(*bufio.Reader)
if !ok {
+2 -16
View File
@@ -2,22 +2,8 @@ package mcp
import "path/filepath"
// NpmCacheEnv returns environment variables that make an npx-launched MCP
// server reuse a persistent package cache at cacheDir, instead of npm
// re-resolving and re-downloading the package from the registry on every
// launch. Empty for any command other than npx, or an empty cacheDir --
// npx has a registry dependency other commands don't, and an empty cacheDir
// means the caller has no persistent location to point npm at.
//
// This covers the npm package itself, not a package's own separate
// download path -- e.g. Playwright/Puppeteer-based servers fetch browser
// binaries from a CDN via a postinstall script, gated by their own env
// vars, which this does not touch.
//
// Matched by base name, not exact string: a command may be pinned via an
// absolute path (an operator's daemon config, or a container image's PATH),
// and an exact "npx" match would skip the fix silently, with no error
// logged, leaving the underlying registry re-fetch in place unnoticed.
// NpmCacheEnv returns env vars pointing npx's package cache at cacheDir. Empty
// unless command's base name is npx and cacheDir is set.
func NpmCacheEnv(command, cacheDir string) []string {
if filepath.Base(command) != "npx" || cacheDir == "" {
return nil
+2 -5
View File
@@ -54,11 +54,8 @@ type SamplingResult struct {
StopReason string `json:"stopReason,omitempty"`
}
// SamplingHandler answers one server-initiated sampling request from a
// configured model. It returns a Go error for a refused or failed
// completion; the client maps that to a JSON-RPC internal error so the
// server sees the failure for its own request only, never a dropped
// session.
// SamplingHandler answers a server's sampling request. Errors become JSON-RPC
// internal errors.
type SamplingHandler func(ctx context.Context, req SamplingRequest) (SamplingResult, error)
// ServerRequestHandler answers one request the MCP server sent to this
+11 -51
View File
@@ -80,14 +80,8 @@ func (c StdioTransportConfig) effectiveShutdownGrace() time.Duration {
// ── Transport ───────────────────────────────────────────────────────────
// StdioTransport manages an MCP server subprocess, sending JSON-RPC 2.0
// messages to its stdin and receiving responses from its stdout. Messages
// use MCP's newline-delimited JSON framing.
//
// The transport supports automatic restart with exponential backoff when
// the subprocess dies unexpectedly. Use [StdioTransport.Start] to begin,
// [StdioTransport.Send] to exchange messages, and [StdioTransport.Stop]
// to shut down cleanly.
// StdioTransport runs an MCP server subprocess, exchanging newline-delimited
// JSON-RPC over stdin/stdout, and restarts it with backoff when it dies.
type StdioTransport struct {
config StdioTransportConfig
@@ -289,12 +283,7 @@ func (t *StdioTransport) Stop(_ context.Context) error {
return nil
}
// Send writes a JSON-RPC 2.0 request to the subprocess stdin and waits for
// the matching response on stdout. It uses the "id" field from the JSON
// body to correlate the response.
//
// Send returns an error if the transport is not running, if the write fails,
// if the context is cancelled, or if the transport is stopped while waiting.
// Send writes a request and waits for the response with the same id.
func (t *StdioTransport) Send(ctx context.Context, body []byte) ([]byte, error) {
// Extract the message ID from the body for response correlation.
msgID, err := extractMessageID(body)
@@ -356,11 +345,7 @@ func (t *StdioTransport) Send(ctx context.Context, body []byte) ([]byte, error)
}
}
// Notify writes a JSON-RPC 2.0 notification (a message with no "id") to
// the subprocess stdin without waiting for a response -- notifications
// have none by definition. Using [StdioTransport.Send] for a
// notification would hang until ctx is cancelled, since Send always
// waits for a reply keyed by the (absent) id.
// Notify writes a notification without waiting for a response.
func (t *StdioTransport) Notify(ctx context.Context, body []byte) error {
if err := ctx.Err(); err != nil {
return err
@@ -397,20 +382,9 @@ func (t *StdioTransport) startSubprocess(ctx context.Context) error {
return t.commitSpawnedProcess(ctx, cmd, stdin, stdout, false)
}
// commitSpawnedProcess installs a freshly spawned subprocess as the
// transport's active one and starts its reader goroutine. spawnProcess runs
// without t.mu held (it performs a real fork/exec), so a concurrent Stop()
// can close t.stopCh and commit StateStopped while a spawn is still in
// flight. commitSpawnedProcess re-checks stopCh under the lock immediately
// before committing: if Stop() already won, the just-spawned subprocess is
// discarded (killed and reaped) instead of clobbering the Stopped state
// Stop() already reported to its own caller. Both startSubprocess (a fresh
// Start()) and attemptRestart's success path (a crash-triggered restart)
// funnel through this single guarded commit point.
//
// resetStartupFailures resets the spawn-failure counter on success; it is
// true only for attemptRestart, since Start() already resets both crash and
// startup-failure counters itself before the first spawn attempt.
// commitSpawnedProcess installs a spawned subprocess and starts its reader,
// unless Stop has already run, in which case the process is killed.
// resetStartupFailures resets the spawn-failure counter.
func (t *StdioTransport) commitSpawnedProcess(ctx context.Context, cmd *exec.Cmd, stdin io.WriteCloser, stdout *bufio.Reader, resetStartupFailures bool) error {
t.mu.Lock()
if t.isStopped() {
@@ -615,14 +589,8 @@ func (t *StdioTransport) failAllPendingLocked() {
}
}
// attemptRestart runs the auto-restart loop with exponential backoff.
// It is called after a subprocess crash and runs until either the
// transport is stopped, max retries (for spawn failures) are exceeded,
// or the subprocess successfully starts.
//
// Crash loops where the process starts but immediately dies are bounded
// by exponential backoff growing up to MaxBackoff. Spawn failures
// (binary not found, permissions, etc.) count against MaxRetries.
// attemptRestart restarts a crashed subprocess with exponential backoff until
// it starts, the transport stops, or spawn failures reach MaxRetries.
func (t *StdioTransport) attemptRestart(ctx context.Context) {
for {
// Check preconditions under lock.
@@ -698,16 +666,8 @@ func (t *StdioTransport) computeBackoffLocked() time.Duration {
return d
}
// writeMessageWithTimeout writes a framed message to w, bounding the write
// itself (not any subsequent response wait) by timeout. A non-positive
// timeout writes with no bound, matching writeMessage directly.
//
// The write runs in a goroutine so a wedged writer (e.g. a full stdin pipe
// because the subprocess has stopped reading) cannot block the caller past
// timeout. Since io.Writer gives no way to cancel an in-flight Write, the
// goroutine is left to finish on its own if the timeout fires; the errCh
// buffer of 1 lets it deliver into a channel nobody is receiving on anymore
// without leaking.
// writeMessageWithTimeout writes a framed message, giving up after timeout. A
// non-positive timeout waits indefinitely.
func writeMessageWithTimeout(w io.Writer, data []byte, timeout time.Duration) error {
if timeout <= 0 {
return writeMessage(w, data)
+2 -11
View File
@@ -28,17 +28,8 @@ func (c HTTPTransportConfig) effectiveTimeout() time.Duration {
return c.Timeout
}
// HTTPTransport implements [Transport] over HTTP/StreamableHTTP. Each
// [Send] makes an HTTP POST with the JSON-RPC request body and returns the
// JSON-RPC response. [Notify] fires an HTTP POST and discards the response
// body — notifications don't expect a JSON-RPC reply.
//
// This transport is stateless (no persistent connection), so Start/Stop
// are not needed. It satisfies the [Transport] interface directly. Being
// stateless, it has no server→client channel and therefore does not
// implement serverRequestRouter: a server-initiated request (MCP sampling)
// cannot arrive over it at all, rather than arriving and being dropped.
// A deployment that needs sampling must use stdio or SSE.
// HTTPTransport is a stateless HTTP Transport: each Send is a POST. It cannot
// receive server-initiated requests.
type HTTPTransport struct {
config HTTPTransportConfig
client *http.Client
+4 -14
View File
@@ -18,11 +18,8 @@ type SSETransportConfig struct {
// SSEEndpoint is the GET URL for the server→client event stream (e.g.
// "https://mcp.example.com/sse"). Required.
SSEEndpoint string
// MessageEndpoint is the POST URL for client→server messages. When
// empty (the common case), the client discovers it from the
// "endpoint" SSE event sent by the server after connecting — this
// is the MCP SSE spec behaviour; the server's endpoint event carries
// the full POST URL including a session-id query parameter.
// MessageEndpoint is the POST URL for client messages. Empty discovers it
// from the server's "endpoint" event.
MessageEndpoint string
// Headers are additional HTTP headers sent with every request.
Headers map[string]string
@@ -522,15 +519,8 @@ func readEndpointEvent(r *bufio.Reader) (string, error) {
return strings.TrimSpace(data), nil
}
// readSSEEvent reads one complete SSE event from the stream. It returns the
// event type and data payload. SSE fields are:
//
// event: <type>\n
// data: <payload>\n
// \n (blank line terminates the event)
//
// Lines beginning with ':' are comments and are skipped. Multiple "data:"
// lines are concatenated with newlines (per the SSE spec).
// readSSEEvent reads one SSE event and returns its type and data. Comment
// lines are skipped; multiple data lines are joined with newlines.
func readSSEEvent(r *bufio.Reader) (event, data string, err error) {
var dataLines []string
for {
+1 -6
View File
@@ -1,9 +1,4 @@
// Package mcp implements the Model Context Protocol (MCP) transport layer.
//
// The stdio transport manages an MCP server subprocess over stdin/stdout
// using JSON-RPC 2.0 message framing with Content-Length headers (the same
// framing used by LSP). This is the foundational transport that most local
// MCP servers use.
// Package mcp implements an MCP client over stdio, HTTP and SSE transports.
package mcp
import "encoding/json"