refactor(postgres,mcp,archieui,task,prreview,playbook): cut comments down to what the code does
This commit is contained in:
1 parent
2fc11b60e1
commit
1bd738cfe8
38 files changed
+209
-827
No files matched your search
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
}
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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),
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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)
|
||||
}
|
||||
|
||||
@@ -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 {
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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"`
|
||||
|
||||
@@ -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]
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
}
|
||||
|
||||
|
||||
@@ -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"`
|
||||
|
||||
@@ -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,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 {
|
||||
|
||||
@@ -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{
|
||||
|
||||
@@ -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 {
|
||||
|
||||
@@ -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) {
|
||||
|
||||
@@ -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()
|
||||
|
||||
@@ -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,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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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,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"
|
||||
|
||||
Reference in new issue
Block a user