From 8d6c3e3c995bf56a24c8c25eb6c399e7ea767787 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Sun, 27 Sep 2026 05:09:17 +1000 Subject: [PATCH 1/5] fix(archied): republish the config snapshot when live settings apply applyWorkflowExecutionSettings swapped the running config with cfgHolder.Set, so the dashboard's published projection kept the previous budgets until the next reload. Route it through publishConfig like every other config change. Fixes #1148 --- internal/app/archied/config_snapshot_test.go | 29 ++++++++++++++++++++ internal/app/archied/control_plane.go | 2 +- 2 files changed, 30 insertions(+), 1 deletion(-) diff --git a/internal/app/archied/config_snapshot_test.go b/internal/app/archied/config_snapshot_test.go index f08bf34d7..bc088f2af 100644 --- a/internal/app/archied/config_snapshot_test.go +++ b/internal/app/archied/config_snapshot_test.go @@ -5,8 +5,10 @@ import ( "encoding/json" "log/slog" "testing" + "time" "github.com/samcharles93/archie-core/internal/config" + "github.com/samcharles93/archie-core/internal/domain/workflow" "github.com/samcharles93/archie-core/internal/infrastructure/configuration" "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" "github.com/samcharles93/archie-core/internal/webui" @@ -136,3 +138,30 @@ func TestPublishConfigSnapshotWithoutConfiguration(t *testing.T) { t.Fatalf("ConfigSnapshot = (found %v, %v), want nothing published", found, err) } } + +// TestLiveSettingsApplyRepublishesTheConfigSnapshot: the dashboard renders the +// published projection, not the daemon's Holder, so a live apply that changes +// the running config must republish it or the page keeps showing the old +// values until the next reload. +func TestLiveSettingsApplyRepublishesTheConfigSnapshot(t *testing.T) { + st := pgstore.Open(t) + t.Cleanup(func() { _ = st.Close() }) + + b, _ := newLiveApplyBoot(t, fileConfig()) + b.stateStore = st + if err := b.applyWorkflowExecutionSettings(t.Context(), workflow.ExecutionSettings{MaxModelToolSteps: 25, MaxRuntime: time.Hour, MaxConsecutiveGateFailures: 4}, 2); err != nil { + t.Fatalf("live update: %v", err) + } + + snapshot, found, err := st.ConfigSnapshot(context.Background()) + if err != nil || !found { + t.Fatalf("ConfigSnapshot = (found %v, %v), want the live apply to publish one", found, err) + } + var view webui.ConfigView + if err := json.Unmarshal(snapshot.Document, &view); err != nil { + t.Fatalf("decode published document: %v", err) + } + if view.Budgets.MaxSteps != 25 || view.Budgets.GateMaxFailures != 4 { + t.Errorf("published budgets = %+v, want the live-applied limits", view.Budgets) + } +} diff --git a/internal/app/archied/control_plane.go b/internal/app/archied/control_plane.go index d182664d1..eab460c99 100644 --- a/internal/app/archied/control_plane.go +++ b/internal/app/archied/control_plane.go @@ -216,7 +216,7 @@ func (b *boot) applyWorkflowExecutionSettings(ctx context.Context, settings work return err } b.executionSettings.Store(&candidate.settings) - b.cfgHolder.Set(candidate.cfg) + b.publishConfig(ctx, candidate.cfg) b.applyStatus.Report(ctx, controlplane.WorkflowExecutionSettingsKind, version, nil) b.log.Info("workflow execution settings applied", "version", version) if limit, uptime := settings.MaxTaskRuntime, candidate.cfg.Containers.MaxUptime.Std(); uptime > 0 && (limit <= 0 || limit > uptime) { From 04dfa29dcb3850b7986420e5c98e40915d2bdc89 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Sat, 26 Sep 2026 20:42:52 +1000 Subject: [PATCH 2/5] fix(webhook): reject rate-limited deliveries with 429 instead of chat prose or a false 202 Router.Route returned the chat-facing rate-limit prose with a nil error, so the webhook handler had no way to tell a genuine dispatch outcome from a rejection: DeliverTo "origin" echoed the prose as a 200 reply, and any other route got a 202 for an event that was actually dropped before reaching the LLM, so the source never retries it. ChatReply now carries RateLimited, set by a new Router.RouteResult (Route is now a thin wrapper over it) so chat channels that render Text to a human are unaffected. The webhook handler checks it and answers 429, matching the precedent internal/webhookguard.RateLimiter's other callers already set. --- internal/channels/webhook/webhook.go | 11 +++++++++ internal/channels/webhook/webhook_test.go | 29 +++++++++++++++++++++++ internal/domain/messaging/chat_stream.go | 6 +++++ internal/gateway/chat_local.go | 4 ++-- internal/gateway/gateway.go | 16 +++++++++++-- 5 files changed, 62 insertions(+), 4 deletions(-) diff --git a/internal/channels/webhook/webhook.go b/internal/channels/webhook/webhook.go index 2725b0cba..ed958878c 100644 --- a/internal/channels/webhook/webhook.go +++ b/internal/channels/webhook/webhook.go @@ -195,6 +195,17 @@ func (g *Gateway) handleWebhook(route *RouteConfig) http.HandlerFunc { return } + // A rate-limited delivery was dropped before reaching the LLM, not + // completed: it must not be echoed back as a successful "origin" reply + // (chat prose, meant for a human) or 202'd as accepted (indistinguishable + // from a delivered event, so the source would never retry it). 429 lets + // the source back off and retry, the way internal/webhookguard.RateLimiter's + // other callers already respond (archie-core-1173). + if reply.RateLimited { + http.Error(w, "rate limited", http.StatusTooManyRequests) + return + } + if route.DeliverTo == "origin" && reply.Text != "" { w.Header().Set("Content-Type", "text/plain") _, _ = w.Write([]byte(reply.Text)) diff --git a/internal/channels/webhook/webhook_test.go b/internal/channels/webhook/webhook_test.go index 71f31e1a1..6be25ca60 100644 --- a/internal/channels/webhook/webhook_test.go +++ b/internal/channels/webhook/webhook_test.go @@ -120,6 +120,35 @@ func TestWebhookHandlerRoute(t *testing.T) { } } +// TestWebhookHandlerRateLimitedDeliveryIsRejected pins archie-core-1173: a +// rate-limited webhook delivery must be surfaced to the origin as an +// observable rejection (429), never as chat prose echoed back with a 200, and +// never as a 202 that claims a dropped event was accepted (the origin would +// then never retry it). +func TestWebhookHandlerRateLimitedDeliveryIsRejected(t *testing.T) { + for _, deliverTo := range []string{"origin", ""} { + t.Run("DeliverTo="+deliverTo, func(t *testing.T) { + log := slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{Level: slog.LevelWarn})) + g := New("", 0, []RouteConfig{{Path: "/hook", DeliverTo: deliverTo}}, log) + g.client = &fakeChatContract{ + routeFunc: func(context.Context, messaging.Inbound) (messaging.ChatReply, error) { + return messaging.ChatReply{Text: "You're sending messages too quickly. Please wait a moment and try again.", RateLimited: true}, nil + }, + } + + handler := g.WebhookHandler() + rec := httptest.NewRecorder() + handler.ServeHTTP(rec, httptest.NewRequestWithContext(context.Background(), http.MethodPost, "/hook", strings.NewReader(`{"text":"hello"}`))) + if rec.Code != http.StatusTooManyRequests { + t.Errorf("status = %d, want 429 so the origin can back off and retry", rec.Code) + } + if strings.Contains(rec.Body.String(), "too quickly") { + t.Errorf("body = %q, want no chat prose echoed to a webhook origin", rec.Body.String()) + } + }) + } +} + func TestWebhookHandlerInvalidSignature(t *testing.T) { g := New("", 0, []RouteConfig{{Path: "/hook", Secret: "secret"}}, slog.Default()) g.client = &fakeChatContract{} diff --git a/internal/domain/messaging/chat_stream.go b/internal/domain/messaging/chat_stream.go index b190fd412..b7eb4745f 100644 --- a/internal/domain/messaging/chat_stream.go +++ b/internal/domain/messaging/chat_stream.go @@ -24,6 +24,12 @@ type ChatSnapshot struct { type ChatReply struct { Text string SessionID string + // RateLimited reports whether Text is the inbound rate-limit reply rather + // than a real dispatch outcome. A human-facing channel can ignore it and + // send Text as usual; a channel with no human reading replies (a webhook) + // must not treat it as a normal reply or a delivered event -- see + // archie-core-1173. + RateLimited bool } // ChatCancellation is what Cancel returns. diff --git a/internal/gateway/chat_local.go b/internal/gateway/chat_local.go index 218351df5..003f0b9c1 100644 --- a/internal/gateway/chat_local.go +++ b/internal/gateway/chat_local.go @@ -89,12 +89,12 @@ func (a *LocalChatAdapter) RecentTurns(ctx context.Context, id string, n int) ([ } func (a *LocalChatAdapter) Route(ctx context.Context, in Inbound) (ChatReply, error) { - reply, err := a.Router.Route(ctx, in) + reply, rateLimited, err := a.Router.RouteResult(ctx, in) if err != nil { return ChatReply{}, err } id, err := a.Router.ResolveSessionKey(ctx, in) - return ChatReply{Text: reply, SessionID: id}, err + return ChatReply{Text: reply, SessionID: id, RateLimited: rateLimited}, err } func (a *LocalChatAdapter) Cancel(ctx context.Context, id string) (ChatCancellation, error) { diff --git a/internal/gateway/gateway.go b/internal/gateway/gateway.go index f1fc6160a..18ee77569 100644 --- a/internal/gateway/gateway.go +++ b/internal/gateway/gateway.go @@ -269,10 +269,22 @@ func inboundBudgetKey(in Inbound) string { // Route dispatches msg and returns the reply. Gateway-local commands // are handled directly; everything else goes to the LLM responder. func (r *Router) Route(ctx context.Context, in Inbound) (string, error) { + reply, _, err := r.RouteResult(ctx, in) + return reply, err +} + +// RouteResult is Route, plus whether the sender was blocked by its inbound +// rate limit. A caller with a human reading the reply (chat channels) can +// ignore the flag and treat the reply text as usual; a caller with no human +// there (a webhook) needs it to answer with a proper rejection instead of +// echoing the rate-limit prose as a successful delivery, or accepting an +// event that was actually dropped (archie-core-1173). +func (r *Router) RouteResult(ctx context.Context, in Inbound) (reply string, rateLimited bool, err error) { if r.checkRateLimit(in) { - return rateLimitReply, nil + return rateLimitReply, true, nil } - return r.route(ctx, in) + reply, err = r.route(ctx, in) + return reply, false, err } // route is Route's continuation once the caller has already cleared the From adf44d827f0fd7933f993bd5ffa47b89e28efb66 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Sun, 27 Sep 2026 04:53:19 +1000 Subject: [PATCH 3/5] feat(controlplane): agent profiles as their own live control-plane resource docs/prds/external-agent-harness.md ("Selection"): a Kit profile is an org resource that applies without a restart. Profiles were bundled inside container-runtime-policies (ApplyMode: restart-required), which is correct for Image/MaxConcurrency/Network but not for Profiles, which nothing startup-builds: daemon.configFor reads config.Holder fresh per dispatch (pinTaskProfile -> Containers.Profile). Split Profiles into its own resource, AgentProfileKind ("agent-profiles"), ApplyMode: live, seeded from [containers.profiles] and validated with the same rules the file document uses (config.ValidateAgentProfiles, factored out of ContainerConfig.ValidateProfiles so the two cannot disagree). config.ContainerConfig.Profiles is now json:"-" so container-runtime-policies never carries it (one authoritative resource per field, not two), and runtime_config.go layers the new resource in by wholesale map replacement (matching ModelRoleAssignmentsKind's precedent) rather than merging into the file's map. Added Profiles to reload.go's Containers reloadable-subfield set to match this. Deliberately NOT built here: true per-org multi-tenant storage for this resource (docs/prds/orgs-and-access.md places agent profiles under org ownership, granted to workspaces). No existing control-plane resource kind in this registry does real per-org storage yet either -- schedules, workflow settings, etc. are all single instance-wide documents -- so agent-profiles follows that same established, tested pattern rather than inventing org-scoped storage unilaterally for this one resource. Org/ workspace grants over agent-profiles are a follow-on, not a redo: nothing about this resource's shape needs to change to add that scoping later. --- .../skills/archie-config-and-flags/SKILL.md | 1 + internal/app/archied/reload.go | 22 +++--- internal/app/controlplane/agent_profiles.go | 67 +++++++++++++++++++ .../app/controlplane/container_settings.go | 49 +++++++------- .../controlplane/container_settings_test.go | 67 ++++++++----------- internal/app/controlplane/definitions.go | 2 +- internal/app/controlplane/runtime_config.go | 38 ++++++----- .../app/controlplane/runtime_config_test.go | 54 ++++++++++++--- .../app/controlplane/validators_agree_test.go | 8 +-- internal/config/config.go | 17 ++++- 10 files changed, 217 insertions(+), 108 deletions(-) create mode 100644 internal/app/controlplane/agent_profiles.go diff --git a/.agents/skills/archie-config-and-flags/SKILL.md b/.agents/skills/archie-config-and-flags/SKILL.md index 8e003d9b4..0abc8be07 100644 --- a/.agents/skills/archie-config-and-flags/SKILL.md +++ b/.agents/skills/archie-config-and-flags/SKILL.md @@ -175,6 +175,7 @@ looking at before reporting one: | `volume_ttl` | Default `72h` only when enabled; negative rejected. | | `pull_policy` | Default `missing` when enabled. Pool code recognises `missing` and `always`; other strings silently skip pre-pull. | | `network` | Empty uses best-effort self-network detection. Repository overlay pins `archie-core_default`. | +| `profiles` | Named agent execution environments (image or Kit); resolved per task dispatch (`ContainerConfig.Profile`). Own control-plane resource `agent-profiles` (`json:"-"` on the field so `container-runtime-policies` never carries it), `ApplyMode: live` -- a profile change applies without a restart, unlike the rest of `[containers]`. | ### Channel settings diff --git a/internal/app/archied/reload.go b/internal/app/archied/reload.go index e8dbf13fa..073d746a8 100644 --- a/internal/app/archied/reload.go +++ b/internal/app/archied/reload.go @@ -148,16 +148,20 @@ var reloadableFields = map[string]bool{ // reloadableSubFields are sub-fields of structs that are otherwise // startup-built. VolumeTTL is re-read per cycle in cleanupExpiredStorage; -// everything else in Containers (Image, MaxConcurrency, -// MaxUptime, PullPolicy, Network) is frozen in the startup-built -// container pool -- the dispatchers re-read MaxConcurrency but the pool -// captures it at construction (container/pool.go:94,163), so a change -// only partially applies and must warn requires-restart. Forge.Host is -// carried into TaskContext by ForTask (display/link building only); the -// forge client itself is startup-built, so Type/Token/TokenEnv stay -// requires-restart. +// Profiles is resolved fresh per dispatch (daemon.configFor -> +// Containers.Profile, called from pinTaskProfile) and is also its own +// live-applying control-plane resource (AgentProfileKind), never captured at +// container-pool construction -- docs/prds/external-agent-harness.md +// "Selection": a Kit profile applies without a restart. Everything else in +// Containers (Image, MaxConcurrency, MaxUptime, PullPolicy, Network) is +// frozen in the startup-built container pool -- the dispatchers re-read +// MaxConcurrency but the pool captures it at construction +// (container/pool.go:94,163), so a change only partially applies and must +// warn requires-restart. Forge.Host is carried into TaskContext by ForTask +// (display/link building only); the forge client itself is startup-built, so +// Type/Token/TokenEnv stay requires-restart. var reloadableSubFields = map[string]map[string]bool{ - "Containers": {"VolumeTTL": true}, + "Containers": {"VolumeTTL": true, "Profiles": true}, "Forge": {"Host": true}, // Policy is carried into TaskConfig by ForTask (config.go); MCPServers, // WebFetch and Minimax are not and stay requires-restart. diff --git a/internal/app/controlplane/agent_profiles.go b/internal/app/controlplane/agent_profiles.go new file mode 100644 index 000000000..2593acca7 --- /dev/null +++ b/internal/app/controlplane/agent_profiles.go @@ -0,0 +1,67 @@ +package controlplane + +import "github.com/samcharles93/archie-core/internal/config" + +// AgentProfileKind is the control-plane resource for Kit and image agent +// profiles. It exists so a Kit profile applies without a restart +// (docs/prds/external-agent-harness.md, "Selection"): [containers].profiles +// in config.toml is only its seed, ContainerRuntimePoliciesKind carries every +// other container setting and none of this one (config.ContainerConfig. +// Profiles is json:"-"), and this resource's own ApplyMode is "live". +// +// Its document is agentProfile (container_settings.go's snake_case wire +// type), not config.AgentProfile directly: that internal type carries no +// json tags, so encoding/json would fall back to its Go field names -- +// "Tools", "Image" -- exactly the defect archie-core-1171 fixed for the rest +// of this document family. +const AgentProfileKind = "agent-profiles" + +func agentProfileDefinition() Definition { + return Definition{ + Kind: AgentProfileKind, + Title: "Agent profiles", + ApplyMode: "live", + Document: map[string]agentProfile{}, + Seed: seedAgentProfiles, + Validate: validateAgentProfiles, + } +} + +func seedAgentProfiles(cfg config.Config) any { + return agentProfilesDocument(cfg.Containers.Profiles) +} + +// agentProfilesDocument maps the internal type to the document's wire type. +func agentProfilesDocument(profiles map[string]config.AgentProfile) map[string]agentProfile { + if profiles == nil { + return nil + } + out := make(map[string]agentProfile, len(profiles)) + for name, p := range profiles { + out[name] = agentProfile{Image: p.Image, Kit: p.Kit, Adapter: p.Adapter, Tools: p.Tools} + } + return out +} + +// agentProfilesSettings reverses agentProfilesDocument, for the layering in +// runtime_config.go and for validation against config.ValidateAgentProfiles. +func agentProfilesSettings(profiles map[string]agentProfile) map[string]config.AgentProfile { + if profiles == nil { + return nil + } + out := make(map[string]config.AgentProfile, len(profiles)) + for name, p := range profiles { + out[name] = config.AgentProfile{Image: p.Image, Kit: p.Kit, Adapter: p.Adapter, Tools: p.Tools} + } + return out +} + +func validateAgentProfiles(input []byte) error { + // The rules live in the config package and are shared with the file + // document's own validation (config.ContainerConfig.ValidateProfiles): + // which profiles are valid cannot differ between the file that seeds + // this resource and the resource that replaces it. + return validateAs(input, func(profiles map[string]agentProfile) error { + return config.ValidateAgentProfiles(agentProfilesSettings(profiles)) + }) +} diff --git a/internal/app/controlplane/container_settings.go b/internal/app/controlplane/container_settings.go index 061331b5f..2e0074b5b 100644 --- a/internal/app/controlplane/container_settings.go +++ b/internal/app/controlplane/container_settings.go @@ -17,14 +17,18 @@ import ( // "MaxConcurrency", "LegacyEnabled" -- the only Go-cased resource left in the // registry (archie-core-1171). The two durations are config.Duration, which // already writes the string the file accepts; the leak was the keys only. +// +// Profiles is deliberately not a field here: config.ContainerConfig.Profiles +// is json:"-" (its own resource, AgentProfileKind, applies live where the +// rest of this one is restart-required -- docs/prds/external-agent-harness.md +// "Selection"), so this document never carries it either. type containerRuntimePolicies struct { - Image string `json:"image"` - MaxConcurrency int `json:"max_concurrency"` - MaxUptime config.Duration `json:"max_uptime"` - VolumeTTL config.Duration `json:"volume_ttl"` - PullPolicy string `json:"pull_policy"` - Network string `json:"network"` - Profiles map[string]agentProfile `json:"profiles,omitempty"` + Image string `json:"image"` + MaxConcurrency int `json:"max_concurrency"` + MaxUptime config.Duration `json:"max_uptime"` + VolumeTTL config.Duration `json:"volume_ttl"` + PullPolicy string `json:"pull_policy"` + Network string `json:"network"` } // agentProfile is one named execution environment as the document writes it. @@ -43,7 +47,6 @@ type agentProfile struct { var legacyContainerKeys = map[string]string{ "Image": "image", "MaxConcurrency": "max_concurrency", "MaxUptime": "max_uptime", "VolumeTTL": "volume_ttl", "PullPolicy": "pull_policy", "Network": "network", - "Profiles": "profiles", } // legacyProfileKeys are the same fallback at the profile nesting level. @@ -74,6 +77,11 @@ func (p *containerRuntimePolicies) UnmarshalJSON(data []byte) error { // consumer -- so it is dropped rather than renamed: the strict decode would // otherwise refuse a document every deployment of that window stores. delete(raw, "LegacyEnabled") + // "profiles"/"Profiles" carried config.ContainerConfig.Profiles before it + // moved to its own resource, AgentProfileKind; a document stored under + // either name before that still decodes, with the key simply dropped. + delete(raw, "profiles") + delete(raw, "Profiles") encoded, err := json.Marshal(raw) if err != nil { return err @@ -87,33 +95,22 @@ func (p *containerRuntimePolicies) UnmarshalJSON(data []byte) error { } // settings maps the document onto the internal config struct the daemon runs. +// Profiles is never set here: config.ContainerConfig.Profiles is json:"-", +// and AgentProfileKind's own layering step in runtime_config.go is what sets +// it, after this one runs. func (p containerRuntimePolicies) settings() config.ContainerConfig { - out := config.ContainerConfig{ + return config.ContainerConfig{ Image: p.Image, MaxConcurrency: p.MaxConcurrency, MaxUptime: p.MaxUptime, VolumeTTL: p.VolumeTTL, PullPolicy: p.PullPolicy, Network: p.Network, } - if p.Profiles != nil { - out.Profiles = make(map[string]config.AgentProfile, len(p.Profiles)) - for name, profile := range p.Profiles { - out.Profiles[name] = config.AgentProfile{Image: profile.Image, Kit: profile.Kit, Adapter: profile.Adapter, Tools: profile.Tools} - } - } - return out } func seedContainerPolicies(cfg config.Config) any { containers := cfg.Containers - policies := containerRuntimePolicies{ + return containerRuntimePolicies{ Image: containers.Image, MaxConcurrency: containers.MaxConcurrency, MaxUptime: containers.MaxUptime, VolumeTTL: containers.VolumeTTL, PullPolicy: containers.PullPolicy, Network: containers.Network, } - if containers.Profiles != nil { - policies.Profiles = make(map[string]agentProfile, len(containers.Profiles)) - for name, profile := range containers.Profiles { - policies.Profiles[name] = agentProfile{Image: profile.Image, Kit: profile.Kit, Adapter: profile.Adapter, Tools: profile.Tools} - } - } - return policies } func validateContainers(input []byte) error { @@ -130,7 +127,9 @@ func validateContainers(input []byte) error { if strings.TrimSpace(settings.Image) == "" { return fmt.Errorf("container image is required for autonomous workflow workers") } - return settings.ValidateProfiles() + // Profiles is json:"-" on config.ContainerConfig: it is + // AgentProfileKind's document now, validated there. + return nil }) } diff --git a/internal/app/controlplane/container_settings_test.go b/internal/app/controlplane/container_settings_test.go index ceea747fc..3fc144374 100644 --- a/internal/app/controlplane/container_settings_test.go +++ b/internal/app/controlplane/container_settings_test.go @@ -33,7 +33,6 @@ func TestContainerRuntimePoliciesSeedIsTheDocumentShape(t *testing.T) { Image: "archie-agent:test", MaxConcurrency: 4, MaxUptime: config.Duration(2 * time.Hour), VolumeTTL: config.Duration(24 * time.Hour), PullPolicy: "missing", Network: "bridge", - Profiles: map[string]config.AgentProfile{"net": {Tools: []string{"whois"}}}, }} encoded, err := json.Marshal(containerPoliciesDefinition(t).Seed(cfg)) if err != nil { @@ -53,33 +52,31 @@ func TestContainerRuntimePoliciesSeedIsTheDocumentShape(t *testing.T) { t.Errorf("seed %s = %#v, want %#v", key, document[key], value) } } - profiles, ok := document["profiles"].(map[string]any) - if !ok { - t.Fatalf("profiles = %#v, want an object", document["profiles"]) - } - net, ok := profiles["net"].(map[string]any) - if !ok || net["tools"] == nil { - t.Fatalf("profiles.net = %#v, want the snake_case tools", profiles["net"]) - } // The Go field names encoding/json fell back to when the document was the - // internal config struct -- at both nesting levels. - for _, legacy := range []string{"Image", "MaxConcurrency", "MaxUptime", "VolumeTTL", "PullPolicy", "Network", "Profiles"} { + // internal config struct. + for _, legacy := range []string{"Image", "MaxConcurrency", "MaxUptime", "VolumeTTL", "PullPolicy", "Network"} { if _, present := document[legacy]; present { t.Errorf("seed carries the Go-cased key %q", legacy) } } - for _, legacy := range []string{"Image", "Kit", "Adapter", "Tools"} { - if _, present := net[legacy]; present { - t.Errorf("profiles.net carries the Go-cased key %q", legacy) - } + // Profiles is its own resource (AgentProfileKind, applying live where the + // rest of this document is restart-required), so it never appears here at + // all, under either casing. + if _, present := document["profiles"]; present { + t.Error("seed carries profiles: it belongs to AgentProfileKind now") + } + if _, present := document["Profiles"]; present { + t.Error("seed carries Profiles: it belongs to AgentProfileKind now") } } // legacyContainerDocument is a document as an earlier revision stored it: the // Go field names encoding/json fell back to while the document was the internal -// config struct, and LegacyEnabled from the short window in which the removed -// containers.enabled switch still decoded. Every store written before the -// reshape holds a document like this one, so it has to keep working. +// config struct, LegacyEnabled from the short window in which the removed +// containers.enabled switch still decoded, and Profiles from before it moved to +// its own resource, AgentProfileKind. Every store written before either reshape +// holds a document like this one, so it has to keep working -- Profiles simply +// drops, the way LegacyEnabled already does. const legacyContainerDocument = `{"Image":"archie-agent:test","MaxConcurrency":4,"MaxUptime":"2h0m0s","VolumeTTL":"24h0m0s","PullPolicy":"missing","Network":"bridge","LegacyEnabled":false,"Profiles":{"net":{"Image":"proxy:1","Tools":["whois"]}}}` // TestContainerRuntimePoliciesReadsADocumentWrittenBeforeTheReshape covers the @@ -99,7 +96,7 @@ func TestContainerRuntimePoliciesReadsADocumentWrittenBeforeTheReshape(t *testin if err != nil { t.Fatalf("Decode(legacy) = %v", err) } - for _, legacy := range []string{`"Image"`, `"MaxConcurrency"`, `"LegacyEnabled"`, `"Profiles"`, `"Tools"`} { + for _, legacy := range []string{`"Image"`, `"MaxConcurrency"`, `"LegacyEnabled"`, `"Profiles"`, `"profiles"`} { if strings.Contains(string(decoded), legacy) { t.Fatalf("decoded document = %s, want the canonical keys without %q", decoded, legacy) } @@ -111,10 +108,6 @@ func TestContainerRuntimePoliciesReadsADocumentWrittenBeforeTheReshape(t *testin VolumeTTL string `json:"volume_ttl"` PullPolicy string `json:"pull_policy"` Network string `json:"network"` - Profiles map[string]struct { - Image string `json:"image"` - Tools []string `json:"tools"` - } `json:"profiles"` } if err := json.Unmarshal(decoded, &document); err != nil { t.Fatalf("unmarshal decoded document: %v", err) @@ -124,23 +117,16 @@ func TestContainerRuntimePoliciesReadsADocumentWrittenBeforeTheReshape(t *testin document.PullPolicy != "missing" || document.Network != "bridge" { t.Errorf("document = %+v, want the legacy values preserved in the current shape", document) } - if len(document.Profiles) != 1 || document.Profiles["net"].Image != "proxy:1" { - t.Errorf("profiles = %+v, want the legacy values preserved", document.Profiles) - } } // TestContainerRuntimePoliciesKeepsDisallowUnknownFields: the legacy tolerance -// renames the keys an existing store holds and nothing else, because swallowing -// an unknown key decodes as "unset" and an unset image is a broken worker. A -// misspelling is refused, at the top level and inside a profile. +// renames the keys an existing store holds and nothing else (plus dropping +// profiles/Profiles, which no longer belongs to this document at all), because +// swallowing any other unknown key decodes as "unset" and an unset image is a +// broken worker. func TestContainerRuntimePoliciesKeepsDisallowUnknownFields(t *testing.T) { - for _, document := range []string{ - `{"image":"archie-agent:test","maxconcurrency":4}`, - `{"image":"archie-agent:test","profiles":{"net":{"toolz":["whois"]}}}`, - } { - if err := containerPoliciesDefinition(t).Validate([]byte(document)); err == nil { - t.Errorf("Validate(%s) accepted a misspelled key", document) - } + if err := containerPoliciesDefinition(t).Validate([]byte(`{"image":"archie-agent:test","maxconcurrency":4}`)); err == nil { + t.Error("Validate accepted a misspelled key") } } @@ -155,7 +141,7 @@ func TestContainerRuntimePoliciesLayersLegacyDocuments(t *testing.T) { }{ { name: "the current shape", - stored: `{"image":"archie-agent:test","max_concurrency":4,"max_uptime":"2h0m0s","volume_ttl":"24h0m0s","pull_policy":"missing","network":"bridge","profiles":{"net":{"image":"proxy:1","tools":["whois"]}}}`, + stored: `{"image":"archie-agent:test","max_concurrency":4,"max_uptime":"2h0m0s","volume_ttl":"24h0m0s","pull_policy":"missing","network":"bridge"}`, }, { name: "the Go-cased shape an existing store holds", @@ -175,8 +161,11 @@ func TestContainerRuntimePoliciesLayersLegacyDocuments(t *testing.T) { got.Containers.MaxUptime != config.Duration(2*time.Hour) || got.Containers.Network != "bridge" { t.Fatalf("Containers = %+v, want the stored document applied", got.Containers) } - if len(got.Containers.Profiles) != 1 || got.Containers.Profiles["net"].Image != "proxy:1" { - t.Fatalf("Profiles = %+v, want the stored profiles applied", got.Containers.Profiles) + // Profiles is AgentProfileKind's document now, not this one's; this + // resource carries none, under either casing, so it never reaches + // out.Containers.Profiles. + if len(got.Containers.Profiles) != 0 { + t.Fatalf("Profiles = %+v, want none: container-runtime-policies carries no profiles", got.Containers.Profiles) } }) } diff --git a/internal/app/controlplane/definitions.go b/internal/app/controlplane/definitions.go index 937eeaea0..b01955342 100644 --- a/internal/app/controlplane/definitions.go +++ b/internal/app/controlplane/definitions.go @@ -8,7 +8,7 @@ import ( // Schemas are not declared here: each Definition names its document type, and // Definition.Descriptor derives the JSON Schema from it (internal/app/controlplane/schema.go). func builtinDefinitions(steps workflow.StepRegistry) []Definition { - definitions := []Definition{workflowDefinition(), workflowDefinitionsDefinition(steps), personaDefinition(), scheduleDefinition()} + definitions := []Definition{workflowDefinition(), workflowDefinitionsDefinition(steps), personaDefinition(), scheduleDefinition(), agentProfileDefinition()} definitions = append(definitions, modelDefinitions()...) definitions = append(definitions, operationalDefinitions()...) return definitions diff --git a/internal/app/controlplane/runtime_config.go b/internal/app/controlplane/runtime_config.go index 549f36325..c90f07ed2 100644 --- a/internal/app/controlplane/runtime_config.go +++ b/internal/app/controlplane/runtime_config.go @@ -204,29 +204,33 @@ func runtimeToolConfigFrom(ctx context.Context, reader controlplanerpc.ResourceR return config.Config{}, nil, err } if err := layerResource(ctx, reader, versions, ContainerRuntimePoliciesKind, func(value []byte) error { - // A document that omits profiles (one stored before they existed) - // inherits the file's. One that carries them replaces the file's: - // the mapping below would otherwise merge into the file's map, so a - // profile deleted from the store would come back from the file. Both - // spellings are checked, because documents written before the document - // had its own shape carry the Go-cased key. - var keys map[string]json.RawMessage - if err := json.Unmarshal(value, &keys); err != nil { - return err - } - _, carriesProfiles := keys["profiles"] - if !carriesProfiles { - _, carriesProfiles = keys["Profiles"] - } var policies containerRuntimePolicies if err := json.Unmarshal(value, &policies); err != nil { return err } - inherited := out.Containers.Profiles + // Profiles survives this assignment untouched: containerRuntimePolicies + // carries no Profiles field at all (it is AgentProfileKind's document + // now), and settings() never sets it, so whatever the AgentProfileKind + // layering step below assigns is what's left standing regardless of + // which of the two runs first. + profiles := out.Containers.Profiles out.Containers = policies.settings() - if !carriesProfiles { - out.Containers.Profiles = inherited + out.Containers.Profiles = profiles + return nil + }); err != nil { + return config.Config{}, nil, err + } + // AgentProfileKind is a separate resource from ContainerRuntimePoliciesKind + // (config.ContainerConfig.Profiles is json:"-") so a Kit profile applies + // without a restart: a stored value replaces the file's outright rather + // than merging into it, the same reason ModelRoleAssignmentsKind above + // reassigns out.Models wholesale instead of decoding into the existing map. + if err := layerResource(ctx, reader, versions, AgentProfileKind, func(value []byte) error { + var profiles map[string]agentProfile + if err := json.Unmarshal(value, &profiles); err != nil { + return err } + out.Containers.Profiles = agentProfilesSettings(profiles) return nil }); err != nil { return config.Config{}, nil, err diff --git a/internal/app/controlplane/runtime_config_test.go b/internal/app/controlplane/runtime_config_test.go index efc59d804..91f16ef44 100644 --- a/internal/app/controlplane/runtime_config_test.go +++ b/internal/app/controlplane/runtime_config_test.go @@ -59,6 +59,7 @@ func TestRuntimeConfigUsesDatabaseResourcesAndPreservesBootstrapOnlySecrets(t *t ToolSettingsKind: map[string]any{"mcp_servers": []map[string]any{{"name": "docs", "transport": "http", "url": "https://mcp.example.com", "headers_configured": true}}, "policy": map[string]any{}, "web_fetch": map[string]any{}, "minimax": map[string]any{"enabled": false, "credential_configured": false}}, PluginSettingsKind: map[string]any{"plugin_dir": "/plugins", "module_dir": "/modules", "secret_engine_dir": "/secrets", "skills_dir": "/skills"}, ContainerRuntimePoliciesKind: map[string]any{"image": "archie:next", "pull_policy": "missing"}, + AgentProfileKind: map[string]any{"net": map[string]any{"tools": []string{"whois"}}}, }}) got, versions, err := client.RuntimeConfig(t.Context(), base) @@ -69,7 +70,7 @@ func TestRuntimeConfigUsesDatabaseResourcesAndPreservesBootstrapOnlySecrets(t *t // publishes is the one it actually layered in (archie-core-pskb). for _, kind := range []string{ ProviderSettingsKind, ModelRoleAssignmentsKind, RepositoryPoliciesKind, ChannelSettingsKind, - SchedulingPolicyKind, ToolSettingsKind, PluginSettingsKind, ContainerRuntimePoliciesKind, + SchedulingPolicyKind, ToolSettingsKind, PluginSettingsKind, ContainerRuntimePoliciesKind, AgentProfileKind, } { if versions[kind] != 2 { t.Errorf("versions[%s] = %d, want the 2 the store answered with", kind, versions[kind]) @@ -551,7 +552,7 @@ func TestRuntimeResourceKindsApplyLive(t *testing.T) { modes[definition.Kind] = definition.ApplyMode } for _, kind := range []string{ - ProviderSettingsKind, ModelRoleAssignmentsKind, RepositoryPoliciesKind, SchedulingPolicyKind, + ProviderSettingsKind, ModelRoleAssignmentsKind, RepositoryPoliciesKind, SchedulingPolicyKind, AgentProfileKind, } { if modes[kind] != "live" { t.Errorf("%s applies %q, want live: the daemon re-layers this kind on a watch", kind, modes[kind]) @@ -583,31 +584,47 @@ func TestSchedulingPolicySeedCarriesTheLabel(t *testing.T) { } } -// Stored container policies that carry profiles replace the file's outright; -// ones stored before profiles existed inherit the file's. +// absentReader answers every kind as not-found, so a test can exercise +// runtimeConfigFrom's leave-the-file-value-in-effect path (real ImportConfig +// never leaves a kind unseeded, but a store the migration has not reached yet +// -- or a resource kind added after this document was last stored -- does). +type absentReader struct{} + +func (absentReader) Query(context.Context, string, func([]byte) error) (int64, bool, error) { + return 0, false, nil +} + +// A stored AgentProfileKind value replaces the file's profiles outright; no +// stored value at all leaves the file's in effect (agent-profiles is its own +// resource, seeded from but independent of container-runtime-policies, so a +// Kit profile applies without a restart -- docs/prds/external-agent-harness.md +// "Selection"). func TestRuntimeConfigLayersStoredProfiles(t *testing.T) { base := config.Config{Containers: config.ContainerConfig{Image: "agent:1", Profiles: map[string]config.AgentProfile{ "file-only": {Image: "file:1"}, }}} + for _, tt := range []struct { name string stored map[string]any want []string }{ - {name: "stored profiles replace the file's", stored: map[string]any{"image": "agent:2", "profiles": map[string]any{"net": map[string]any{"tools": []string{"whois"}}}}, want: []string{"net"}}, + {name: "a stored value replaces the file's", stored: map[string]any{"net": map[string]any{"tools": []string{"whois"}}}, want: []string{"net"}}, { - // The Go-cased spelling documents written before the document had its - // own shape carry: the profile it names must still replace the file's. - name: "legacy Go-cased profiles replace the file's", - stored: map[string]any{"Image": "agent:2", "Profiles": map[string]any{"net": map[string]any{"Tools": []string{"whois"}}}}, + // The Go-cased spelling documents written before agent-profiles had + // its own document shape carry, at the profile-nesting level + // (agentProfile.UnmarshalJSON): the profile it names must still + // replace the file's. + name: "a legacy Go-cased stored value replaces the file's", + stored: map[string]any{"net": map[string]any{"Tools": []string{"whois"}}}, want: []string{"net"}, }, - {name: "a document without profiles inherits the file's", stored: map[string]any{"image": "agent:2"}, want: []string{"file-only"}}, } { t.Run(tt.name, func(t *testing.T) { client := NewRPCClient(&runtimeConfigClient{values: map[string]any{ SchedulingPolicyKind: map[string]any{"poll_interval": "2m", "dispatch": map[string]any{"trigger": "assignee"}}, - ContainerRuntimePoliciesKind: tt.stored, + ContainerRuntimePoliciesKind: map[string]any{"image": "agent:2"}, + AgentProfileKind: tt.stored, }}) got, _, err := client.RuntimeConfig(t.Context(), base) if err != nil { @@ -622,6 +639,21 @@ func TestRuntimeConfigLayersStoredProfiles(t *testing.T) { } }) } + + t.Run("no stored value inherits the file's", func(t *testing.T) { + got, _, err := runtimeConfigFrom(t.Context(), absentReader{}, base) + if err != nil { + t.Fatalf("runtimeConfigFrom: %v", err) + } + var names []string + for name := range got.Containers.Profiles { + names = append(names, name) + } + if want := []string{"file-only"}; !reflect.DeepEqual(names, want) { + t.Fatalf("profiles = %v, want %v", names, want) + } + }) + if got := base.Containers.Profiles; len(got) != 1 { t.Fatalf("layering mutated the file document's profiles: %v", got) } diff --git a/internal/app/controlplane/validators_agree_test.go b/internal/app/controlplane/validators_agree_test.go index 592325ca4..c11f6374b 100644 --- a/internal/app/controlplane/validators_agree_test.go +++ b/internal/app/controlplane/validators_agree_test.go @@ -112,11 +112,11 @@ func TestResourceValidatorsRejectWhatEffectiveValidationRejects(t *testing.T) { wantErr: false, }, { - name: "container profile with an empty tool name", - kind: ContainerRuntimePoliciesKind, - value: containerRuntimePolicies{Image: "archie-agent:test", Profiles: map[string]agentProfile{ + name: "agent profile with an empty tool name", + kind: AgentProfileKind, + value: map[string]agentProfile{ "net": {Tools: []string{""}}, - }}, + }, mutate: func(cfg *config.Config) { cfg.Containers.Profiles = map[string]config.AgentProfile{"net": {Tools: []string{""}}} }, diff --git a/internal/config/config.go b/internal/config/config.go index 616588eea..0d7683765 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -846,7 +846,11 @@ type ContainerConfig struct { // Profiles are the named agent profiles a workflow selects with // `profile:`. A workflow that names none runs under the default profile: // Image and every tool. - Profiles map[string]AgentProfile `toml:"profiles" yaml:"profiles"` + // Profiles is excluded from the control-plane JSON document + // (container-runtime-policies): profiles are their own resource, + // AgentProfileKind, seeded from this field but validated and stored + // (and reloaded live) separately -- see internal/app/controlplane. + Profiles map[string]AgentProfile `toml:"profiles" yaml:"profiles" json:"-"` } // AgentProfile is a named execution environment for an agent. Secrets and @@ -893,7 +897,16 @@ func (p AgentProfile) IsKit() bool { return len(p.Kit) > 0 } // ValidateProfiles rejects a profile with an empty name, an empty tool // name, or a Kit that is not pinned by digest or also names an image. func (c ContainerConfig) ValidateProfiles() error { - for name, p := range c.Profiles { + return ValidateAgentProfiles(c.Profiles) +} + +// ValidateAgentProfiles is ValidateProfiles's rule set, standalone so the +// control-plane AgentProfileKind resource (internal/app/controlplane) can +// apply the same rules to a stored value: the file document and the +// resource that replaces it must not be able to disagree about which +// profiles are valid. +func ValidateAgentProfiles(profiles map[string]AgentProfile) error { + for name, p := range profiles { if strings.TrimSpace(name) == "" { return fmt.Errorf("containers.profiles: a profile name must not be empty") } From 4d6f49f7f39115f45a0ffc24600ab1eb8eb5f3ae Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Sun, 27 Sep 2026 04:59:07 +1000 Subject: [PATCH 4/5] docs(harness): pin per-stage profile override as workflow.call, not a mid-container switch docs/prds/external-agent-harness.md's "Selection" says a stage may name a different profile than its workflow's. Investigated before writing new runtime code, per instruction not to build container-switching machinery: a Kit task runs in one container provisioned for one profile (Container layout), so a stage needing a different profile cannot be a mid-container runner swap without inventing per-stage re-provisioning the PRD does not ask for and Container layout argues against ("cost scales with the run, not with how many agents it fans out to"). The requirement is already met by workflow.call plus per-task profile resolution, both pre-existing: postgres.Store.StartCall stores the callee's OWN Workflow name (not the caller's), and daemon.pinTaskProfile resolves a task's profile purely from its own WorkflowDefinitionYAML. Chaining these means a stage wanting a different profile is its own callee workflow, started via workflow.call, exactly the way event-automation.md already describes ("the callee runs as its own run with its own agent profile"). No new production code, only a PRD clarification (dev-docs regenerated) plus TestWorkflowCallGivesACalleeItsOwnProfile (daemon_test.go), which closes the gap between two already-tested facts that nothing previously stated together: TestWorkflowCallerConformance (staterpc) proves a callee's Workflow field is independent of its caller's; this proves that independence is what makes Kit-vs-image runner selection independent too, composing a caller pinned to an image profile with a real StartCall- created callee pinned to a Kit profile. --- docs/data/generated/dev-docs.json | 2 +- docs/prds/external-agent-harness.md | 13 ++++++++ internal/daemon/daemon_test.go | 50 +++++++++++++++++++++++++++++ 3 files changed, 64 insertions(+), 1 deletion(-) diff --git a/docs/data/generated/dev-docs.json b/docs/data/generated/dev-docs.json index aed952775..9c602852d 100644 --- a/docs/data/generated/dev-docs.json +++ b/docs/data/generated/dev-docs.json @@ -328,7 +328,7 @@ "url": "/dev/prds/external-agent-harness/", "title": "External agent harnesses", "section": "PRDs", - "body": "# External agent harnesses\n\n**Status:** Approved\n**Authority:** `docs/architecture/agent-system.md` (agent execution as a data\nboundary); settles the harness non-goal deferred by\n`docs/prds/service-decomposition.md`.\n**Compounds with:** `docs/prds/execution-tree-state-machine.md` (a harness\nrun is one `agent` StepExecution), `docs/prds/binding-secret-encryption.md`\n(the at-rest envelope reused for harness credentials).\n\n## Decision\n\nA workflow stage can run on an external coding-agent CLI instead of the\nbuilt-in agent loop: Claude Code, Codex, Pi, OMP, GitHub Copilot CLI, or any\nother CLI packaged as a Docker Sandbox Kit v3. Each authenticates with an API\nkey or the operator's subscription login, and can carry the operator's own\nskills, plugins, subagents and instructions.\n\nTwo boundaries hold regardless of what the harness does:\n\n- **The real credential never enters the container.** The container sees\n sentinel values; archie's egress proxy substitutes the real credential on\n outbound requests and performs OAuth refresh on the host.\n- **Archie's workflow guarantees are enforced outside the harness.** Git,\n protected paths, read-only stages, gates and budgets are checked by archie\n around the process and against the worktree afterwards.\n\n## Kits\n\nA harness is packaged as a Kit v3 image: an OCI image whose\n`vnd.docker.sandbox.kit.descriptor` manifest annotation declares what the\nharness needs. Archie reads descriptors with the published\n`github.com/docker/sandbox-kit-spec/v3/spec` package and does not maintain\nits own descriptor format. Published Kits run unmodified.\n\nArchie is a partial Kit runtime. It implements these capability types:\n\n| Type | Archie behaviour |\n| ------------------- | ----------------------------------------------------------------------------------------- |\n| `credential@1` | Proxy-managed only, described below. |\n| `network-policy@1` | Enforced by the egress proxy. |\n| `volume@1` | A Docker volume keyed by WorkflowExecution, deleted with it. |\n| `lifecycle@1` | Install and startup hooks run on container create. |\n| `agent-sessions@1` | The headless `prompt` and `resume` invocations for the stage. |\n| `agent-skills@1` | The operator's skills store, mounted read-only whatever the Kit asks. |\n| `agent-context@1` | Archie's stage instructions, delivered where the Kit declares. |\n| `resources@1` | Container CPU and memory limits. |\n\nEvery other type fails closed: a required entry refuses the launch, an\noptional one is skipped and recorded on the step. `credential@1` with\n`passthrough: true` and any credential for a forge service are refused.\n\nThe operator's own setup (plugins, subagents, instructions, settings) is a\nmixin Kit the operator builds `FROM` or alongside the harness Kit. It is\nversioned image content, rewritten on every create, never state a run can\nmodify.\n\n## Contract\n\nA harness run is a second implementation of `agentexec.Runner`. It takes the\nsame `Request` and returns the same `Result`, so workflows, the daemon and\nthe State Store do not know which runner ran a stage.\n\n`agent-sessions@1` supplies the invocation. Archie supplies, per CLI, an\noutput adapter that translates the CLI's JSON output stream into\n`ToolCallReporter` calls, `Usage` and a session ID. A CLI with no adapter can\nrun stages with no capture tools, reporting no usage; its token budget falls\nback to wall clock.\n\nWorkflow definition validation rejects, at load time, a stage whose needs the\nselected harness cannot meet: capture tools without an adapter, or a gate\nretry without a `resume` verb.\n\n## Selection\n\nA harness is an agent profile. `docs/prds/event-automation.md` defines a\nprofile as the execution environment a workflow selects; a harness profile\nnames a Kit composition (the workload Kit pinned by digest, and zero or more\nmixin Kits) in place of a container image. Everything else about profiles\nholds: a workflow names its profile, a stage may name a different one, and a\nprofile holds no secrets.\n\n`archie-agent` builds the stage's runner from the stage's profile: the\nai-sdk agent loop for an image profile, the harness runner for a Kit\nprofile. Image profiles, and every workflow already written against them,\nare unchanged. A Kit profile named by no workflow is a validation error.\n\nProfiles are org resources in the State Store, so a Kit profile belongs to\none org, is granted to its workspaces like any profile, and applies without\na restart.\n\n## Organisations\n\n`docs/prds/orgs-and-access.md` is the boundary; a harness adds nothing that\ncrosses it.\n\n- A Kit profile, its credential bindings and its OAuth tokens belong to one\n org. No record is shared between orgs.\n- A harness run is a run like any other: it acts as the workflow's identity,\n under the run credential issued at dispatch.\n- The egress proxy injects a credential only when the run credential carries\n the secret the binding names. A Kit that declares a service the identity is\n not granted gets no credential: a required one refuses the launch, an\n optional one is skipped.\n- A Kit's network policy is what the Kit asks for; the identity's network\n grants are what the org allows. The proxy enforces the intersection.\n- Concurrency slots are counted per binding within its org.\n\n## Credentials\n\nA credential binding maps a Kit's `credential@1` `service` name to an org\nsecret, which the org grants to identities like any secret. The secret holds\none of:\n\n- **API key:** a value in the org's secret store.\n- **OAuth:** tokens captured by the setup terminal, stored in the State Store\n under the at-rest envelope of `binding-secret-encryption.md` with its own\n domain separator.\n\nThe egress proxy resolves the binding for each request against the run\ncredential. The container gets the Kit's sentinel in the named variable or\ncredential file. OAuth refresh happens at the proxy, which intercepts the\nKit's `tokenEndpoint`, so a refreshed token is written to the State Store and\nnever returned to the container.\n\nRuns sharing an OAuth binding share its subscription's rate limit.\n`max_concurrent` on the binding (default 1) caps its simultaneous runs. A\nstage waiting for a slot is `pending`, not `running`.\n\n## Setup terminal\n\nThe dashboard opens a terminal (xterm.js over a WebSocket to a PTY) into an\nephemeral container built from a Kit profile, on the same egress path. The\nmember runs the CLI's own login. The proxy captures the tokens at the token\nendpoint into the org secret the binding names. The container is removed when\nthe terminal closes. No worktree is mounted into it.\n\nOpening the terminal is the `update` action on the secret, decided by the\nAuthorizer like any other; the shipped roles give it to org owners and\nadmins. It is the only interactive path into a harness container.\n\n## Egress\n\nOnly Kit profiles run on the egress path. An image profile keeps the network\naccess its identity is granted, because workflows such as a network\ninvestigator need raw DNS, ICMP and arbitrary TCP that no HTTP proxy\ncarries.\n\n- **Sandbox network.** Each Kit run gets its own internal Docker bridge on\n which the host holds no address. Host services, including those listening\n on every interface, are unreachable from it by any address.\n- **Relay.** One relay container, `archie-agent relay`, sits on the sandbox\n networks under a fixed alias and on the host-reachable network. It\n forwards three fixed ports, to the proxy, NATS and the State Store, and can\n reach nothing else. It holds no secrets.\n- **Proxy.** The proxy runs inside `archied`, listening on the host gateway\n of the host-reachable network. It terminates TLS with a per-daemon CA\n installed into the container at create, identifies the container by a\n per-run proxy token, and applies that run's network policy and credential\n inject rules. Upstream dials refuse loopback, and refuse internal addresses\n unless the policy names the exact IP, so an allowed name cannot resolve\n back into the host.\n\n## Container layout\n\nA Kit task runs in one container, from the Kit composition's image, on the\ntask's sandbox network. The worker and every harness invocation share it;\nthey are separated by user, not by container, so a run's cost scales with\nthe run and not with how many agents it fans out to.\n\n- **Worker.** Archie mounts its own `archie-agent` binary read-only and runs\n it as the container's entrypoint, as root. It holds the task's NATS and\n State Store credentials in its own environment and in root-only files,\n runs the workflow, and serves `archie-agent mcp`. The Kit image's\n entrypoint is not PID 1.\n- **Harness.** Every invocation runs as the Kit's user (the image's `User`,\n default uid 1000) with an explicit environment: the Kit's variables, the\n proxy environment and the credential sentinels, and nothing inherited from\n the worker. That user cannot read the worker's environment or files, or\n trace it. Sibling invocations in one run share the user and the worktree.\n- **Hooks.** `lifecycle@1` install and startup hooks run as the user each\n declares, before the worker accepts work.\n- **Mounts.** The task worktree at the Kit's workspace directory, owned by the\n Kit's user, and the read-only skills store. Nothing else from the host.\n- **Network.** The relay forwards three fixed ports on the sandbox network:\n the egress proxy, NATS and the State Store. The worker reaches NATS and the\n State Store with its credentials; a harness can open those ports but holds\n no credential either accepts.\n- **Volumes.** `volume@1` paths persist for the life of the\n WorkflowExecution, which covers session resume across gate iterations and\n retries. They are not shared between executions.\n\n## Archie tools inside the harness\n\nCapture tools, which are how a stage returns structured results, are served\nby `archie-agent mcp`, a stdio MCP server registered through the Kit's MCP\nconfiguration or the adapter's flags. It serves the stage's `CaptureTools`\nand the central tools the agent profile's `AllowTools` permits, never the\n`workspace` toolset. The runner's `ToolLimits` bound its results; the\nharness's own built-in tools are outside archie's limits.\n\n## Enforcement around the harness\n\n| Property | Enforcement |\n| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Model never runs git | No forge credential can be bound. Archie records `HEAD` and every ref before the run; any change fails the step (`failed`, policy class). The workflow commits the stage's changes. |\n| Protected paths | A diff touching a `Protection` path fails the step. |\n| Read-only stage | Any worktree diff fails the step. |\n| Gate | Archie runs the stage's gate after the harness exits. On failure it resumes the session with the gate output, up to the stage's iteration budget. |\n| Budget | Archie kills the process on wall-clock timeout, or when streamed usage passes the token budget. |\n| Cancellation | Cancelling the step kills the process group, then the container. |\n| Egress | Only the proxy is reachable; the Kit's network policy decides the rest. |\n\nHarness settings that deny git or protected paths are added where the CLI\nsupports them, to save wasted turns. They are never the enforcement.\n\n## Execution tree\n\nA harness run is one `agent` StepExecution. Subagents the harness spawns\ninternally are not recorded as children. Their usage is included in the\nstep's `tokens_used` when the adapter reports it.\n\n## Agents never hold a harness\n\nAn Agent reaches a harness only by invoking a Workflow whose stage names it.\nNo Agent tool, chat tool or capability exposes a harness, its setup terminal\nor its credential. The stage boundary is what carries the container, the git\nand path checks, the gate and the budget; a harness outside a stage has none\nof them.\n\n## Out of scope\n\n- Chat through a harness. The gateway chat loop stays on the built-in\n runtime.\n- `network-policy@2` HTTP method and path rules; a Kit requiring it is\n refused.\n- Recording the harness's internal subagents as StepExecutions.\n- Cost in currency.\n- Choosing a harness automatically per task.\n\n## Plan\n\n1. Descriptor resolution with the Kit spec package; capability support\n table and fail-closed refusal.\n2. Egress proxy: internal network, per-daemon CA, per-container token,\n `network-policy@1`.\n3. `credential@1`: API-key bindings, sentinel rendering, inject rules.\n4. Harness `Runner`: container create with worktree, volumes, lifecycle\n hooks and the mounted `archie-agent`; `agent-sessions@1` invocation;\n worktree checks for git, protected paths and read-only; budget and\n cancellation.\n5. Claude Code output adapter; `archie-agent mcp`; gate-and-resume loop.\n6. Kit profiles, runner selection from the stage's profile, and definition\n validation.\n7. OAuth bindings as org secrets: token-endpoint interception, encrypted\n storage, per-binding concurrency; dashboard setup terminal.\n8. Output adapters for Codex, Pi, OMP and GitHub Copilot CLI.\n\n## Verification\n\n- The same workflow definition completes on `builtin` and on the Claude Code\n Kit with the same `Result` shape and captures.\n- After `/login` in the setup terminal, the container's credential file holds\n only sentinels, the State Store holds the encrypted token, and a task run\n authenticates.\n- A real API key or OAuth token never appears in the container environment,\n filesystem, worktree, task log or event stream.\n- A request to a host outside the Kit's runtime allow list fails, including a\n direct connection that bypasses the proxy settings.\n- A harness instructed to `git commit` fails its step, and the task branch is\n unchanged.\n- A harness edit to a protected test file fails the step in a TDD fix stage.\n- A read-only feasibility stage that writes a file fails.\n- A file a run writes into a Kit-managed path such as the CLI's settings file\n is gone on the next execution.\n- A Kit requiring an unsupported capability is refused at launch with the\n capability named.\n- A stage with a failing gate resumes the same session with the gate output,\n then succeeds or exhausts its iterations.\n- Two tasks sharing an OAuth binding with `max_concurrent = 1` run one at a\n time; the second waits as `pending`.\n- Stopping a run kills the harness process and removes the container.\n- A harness invocation cannot read the worker's NATS or State Store\n credential from its environment, its files or `/proc`.\n- A run fanning out to many agent invocations uses one container.\n- A Kit profile in org A cannot be selected, and its binding cannot be\n resolved, by a workflow in org B.\n- A harness run whose identity is not granted a Kit's required credential is\n refused at launch; the proxy never injects a secret outside the run\n credential.\n- The firewall investigation example runs unchanged on an image profile with\n direct network access.\n" + "body": "# External agent harnesses\n\n**Status:** Approved\n**Authority:** `docs/architecture/agent-system.md` (agent execution as a data\nboundary); settles the harness non-goal deferred by\n`docs/prds/service-decomposition.md`.\n**Compounds with:** `docs/prds/execution-tree-state-machine.md` (a harness\nrun is one `agent` StepExecution), `docs/prds/binding-secret-encryption.md`\n(the at-rest envelope reused for harness credentials).\n\n## Decision\n\nA workflow stage can run on an external coding-agent CLI instead of the\nbuilt-in agent loop: Claude Code, Codex, Pi, OMP, GitHub Copilot CLI, or any\nother CLI packaged as a Docker Sandbox Kit v3. Each authenticates with an API\nkey or the operator's subscription login, and can carry the operator's own\nskills, plugins, subagents and instructions.\n\nTwo boundaries hold regardless of what the harness does:\n\n- **The real credential never enters the container.** The container sees\n sentinel values; archie's egress proxy substitutes the real credential on\n outbound requests and performs OAuth refresh on the host.\n- **Archie's workflow guarantees are enforced outside the harness.** Git,\n protected paths, read-only stages, gates and budgets are checked by archie\n around the process and against the worktree afterwards.\n\n## Kits\n\nA harness is packaged as a Kit v3 image: an OCI image whose\n`vnd.docker.sandbox.kit.descriptor` manifest annotation declares what the\nharness needs. Archie reads descriptors with the published\n`github.com/docker/sandbox-kit-spec/v3/spec` package and does not maintain\nits own descriptor format. Published Kits run unmodified.\n\nArchie is a partial Kit runtime. It implements these capability types:\n\n| Type | Archie behaviour |\n| ------------------- | ----------------------------------------------------------------------------------------- |\n| `credential@1` | Proxy-managed only, described below. |\n| `network-policy@1` | Enforced by the egress proxy. |\n| `volume@1` | A Docker volume keyed by WorkflowExecution, deleted with it. |\n| `lifecycle@1` | Install and startup hooks run on container create. |\n| `agent-sessions@1` | The headless `prompt` and `resume` invocations for the stage. |\n| `agent-skills@1` | The operator's skills store, mounted read-only whatever the Kit asks. |\n| `agent-context@1` | Archie's stage instructions, delivered where the Kit declares. |\n| `resources@1` | Container CPU and memory limits. |\n\nEvery other type fails closed: a required entry refuses the launch, an\noptional one is skipped and recorded on the step. `credential@1` with\n`passthrough: true` and any credential for a forge service are refused.\n\nThe operator's own setup (plugins, subagents, instructions, settings) is a\nmixin Kit the operator builds `FROM` or alongside the harness Kit. It is\nversioned image content, rewritten on every create, never state a run can\nmodify.\n\n## Contract\n\nA harness run is a second implementation of `agentexec.Runner`. It takes the\nsame `Request` and returns the same `Result`, so workflows, the daemon and\nthe State Store do not know which runner ran a stage.\n\n`agent-sessions@1` supplies the invocation. Archie supplies, per CLI, an\noutput adapter that translates the CLI's JSON output stream into\n`ToolCallReporter` calls, `Usage` and a session ID. A CLI with no adapter can\nrun stages with no capture tools, reporting no usage; its token budget falls\nback to wall clock.\n\nWorkflow definition validation rejects, at load time, a stage whose needs the\nselected harness cannot meet: capture tools without an adapter, or a gate\nretry without a `resume` verb.\n\n## Selection\n\nA harness is an agent profile. `docs/prds/event-automation.md` defines a\nprofile as the execution environment a workflow selects; a harness profile\nnames a Kit composition (the workload Kit pinned by digest, and zero or more\nmixin Kits) in place of a container image. Everything else about profiles\nholds: a workflow names its profile, a stage may name a different one, and a\nprofile holds no secrets.\n\n`archie-agent` builds the stage's runner from the stage's profile: the\nai-sdk agent loop for an image profile, the harness runner for a Kit\nprofile. Image profiles, and every workflow already written against them,\nare unchanged. A Kit profile named by no workflow is a validation error.\n\nA stage naming a different profile than its workflow's is a separate run,\nnot a mid-container runner switch: a Kit task runs in one container\nprovisioned for one profile (Container layout), so a stage that needs a\ndifferent one is its own callee, started the way `workflow.call` already\nstarts one (`docs/prds/event-automation.md` \"Workflows call workflows\"),\nwith its own agent profile resolved off its own task row. This needs no\nmechanism beyond `workflow.call` plus per-task profile resolution\n(`daemon.pinTaskProfile`), both of which already treat every task's\nprofile independently of any caller's -- see\n`TestWorkflowCallerConformance` (staterpc) for the callee's independent\n`Workflow` field and `TestWorkflowCallGivesACalleeItsOwnProfile` (daemon)\nfor the Kit-vs-image runner selection that independence produces.\n\nProfiles are org resources in the State Store, so a Kit profile belongs to\none org, is granted to its workspaces like any profile, and applies without\na restart.\n\n## Organisations\n\n`docs/prds/orgs-and-access.md` is the boundary; a harness adds nothing that\ncrosses it.\n\n- A Kit profile, its credential bindings and its OAuth tokens belong to one\n org. No record is shared between orgs.\n- A harness run is a run like any other: it acts as the workflow's identity,\n under the run credential issued at dispatch.\n- The egress proxy injects a credential only when the run credential carries\n the secret the binding names. A Kit that declares a service the identity is\n not granted gets no credential: a required one refuses the launch, an\n optional one is skipped.\n- A Kit's network policy is what the Kit asks for; the identity's network\n grants are what the org allows. The proxy enforces the intersection.\n- Concurrency slots are counted per binding within its org.\n\n## Credentials\n\nA credential binding maps a Kit's `credential@1` `service` name to an org\nsecret, which the org grants to identities like any secret. The secret holds\none of:\n\n- **API key:** a value in the org's secret store.\n- **OAuth:** tokens captured by the setup terminal, stored in the State Store\n under the at-rest envelope of `binding-secret-encryption.md` with its own\n domain separator.\n\nThe egress proxy resolves the binding for each request against the run\ncredential. The container gets the Kit's sentinel in the named variable or\ncredential file. OAuth refresh happens at the proxy, which intercepts the\nKit's `tokenEndpoint`, so a refreshed token is written to the State Store and\nnever returned to the container.\n\nRuns sharing an OAuth binding share its subscription's rate limit.\n`max_concurrent` on the binding (default 1) caps its simultaneous runs. A\nstage waiting for a slot is `pending`, not `running`.\n\n## Setup terminal\n\nThe dashboard opens a terminal (xterm.js over a WebSocket to a PTY) into an\nephemeral container built from a Kit profile, on the same egress path. The\nmember runs the CLI's own login. The proxy captures the tokens at the token\nendpoint into the org secret the binding names. The container is removed when\nthe terminal closes. No worktree is mounted into it.\n\nOpening the terminal is the `update` action on the secret, decided by the\nAuthorizer like any other; the shipped roles give it to org owners and\nadmins. It is the only interactive path into a harness container.\n\n## Egress\n\nOnly Kit profiles run on the egress path. An image profile keeps the network\naccess its identity is granted, because workflows such as a network\ninvestigator need raw DNS, ICMP and arbitrary TCP that no HTTP proxy\ncarries.\n\n- **Sandbox network.** Each Kit run gets its own internal Docker bridge on\n which the host holds no address. Host services, including those listening\n on every interface, are unreachable from it by any address.\n- **Relay.** One relay container, `archie-agent relay`, sits on the sandbox\n networks under a fixed alias and on the host-reachable network. It\n forwards three fixed ports, to the proxy, NATS and the State Store, and can\n reach nothing else. It holds no secrets.\n- **Proxy.** The proxy runs inside `archied`, listening on the host gateway\n of the host-reachable network. It terminates TLS with a per-daemon CA\n installed into the container at create, identifies the container by a\n per-run proxy token, and applies that run's network policy and credential\n inject rules. Upstream dials refuse loopback, and refuse internal addresses\n unless the policy names the exact IP, so an allowed name cannot resolve\n back into the host.\n\n## Container layout\n\nA Kit task runs in one container, from the Kit composition's image, on the\ntask's sandbox network. The worker and every harness invocation share it;\nthey are separated by user, not by container, so a run's cost scales with\nthe run and not with how many agents it fans out to.\n\n- **Worker.** Archie mounts its own `archie-agent` binary read-only and runs\n it as the container's entrypoint, as root. It holds the task's NATS and\n State Store credentials in its own environment and in root-only files,\n runs the workflow, and serves `archie-agent mcp`. The Kit image's\n entrypoint is not PID 1.\n- **Harness.** Every invocation runs as the Kit's user (the image's `User`,\n default uid 1000) with an explicit environment: the Kit's variables, the\n proxy environment and the credential sentinels, and nothing inherited from\n the worker. That user cannot read the worker's environment or files, or\n trace it. Sibling invocations in one run share the user and the worktree.\n- **Hooks.** `lifecycle@1` install and startup hooks run as the user each\n declares, before the worker accepts work.\n- **Mounts.** The task worktree at the Kit's workspace directory, owned by the\n Kit's user, and the read-only skills store. Nothing else from the host.\n- **Network.** The relay forwards three fixed ports on the sandbox network:\n the egress proxy, NATS and the State Store. The worker reaches NATS and the\n State Store with its credentials; a harness can open those ports but holds\n no credential either accepts.\n- **Volumes.** `volume@1` paths persist for the life of the\n WorkflowExecution, which covers session resume across gate iterations and\n retries. They are not shared between executions.\n\n## Archie tools inside the harness\n\nCapture tools, which are how a stage returns structured results, are served\nby `archie-agent mcp`, a stdio MCP server registered through the Kit's MCP\nconfiguration or the adapter's flags. It serves the stage's `CaptureTools`\nand the central tools the agent profile's `AllowTools` permits, never the\n`workspace` toolset. The runner's `ToolLimits` bound its results; the\nharness's own built-in tools are outside archie's limits.\n\n## Enforcement around the harness\n\n| Property | Enforcement |\n| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Model never runs git | No forge credential can be bound. Archie records `HEAD` and every ref before the run; any change fails the step (`failed`, policy class). The workflow commits the stage's changes. |\n| Protected paths | A diff touching a `Protection` path fails the step. |\n| Read-only stage | Any worktree diff fails the step. |\n| Gate | Archie runs the stage's gate after the harness exits. On failure it resumes the session with the gate output, up to the stage's iteration budget. |\n| Budget | Archie kills the process on wall-clock timeout, or when streamed usage passes the token budget. |\n| Cancellation | Cancelling the step kills the process group, then the container. |\n| Egress | Only the proxy is reachable; the Kit's network policy decides the rest. |\n\nHarness settings that deny git or protected paths are added where the CLI\nsupports them, to save wasted turns. They are never the enforcement.\n\n## Execution tree\n\nA harness run is one `agent` StepExecution. Subagents the harness spawns\ninternally are not recorded as children. Their usage is included in the\nstep's `tokens_used` when the adapter reports it.\n\n## Agents never hold a harness\n\nAn Agent reaches a harness only by invoking a Workflow whose stage names it.\nNo Agent tool, chat tool or capability exposes a harness, its setup terminal\nor its credential. The stage boundary is what carries the container, the git\nand path checks, the gate and the budget; a harness outside a stage has none\nof them.\n\n## Out of scope\n\n- Chat through a harness. The gateway chat loop stays on the built-in\n runtime.\n- `network-policy@2` HTTP method and path rules; a Kit requiring it is\n refused.\n- Recording the harness's internal subagents as StepExecutions.\n- Cost in currency.\n- Choosing a harness automatically per task.\n\n## Plan\n\n1. Descriptor resolution with the Kit spec package; capability support\n table and fail-closed refusal.\n2. Egress proxy: internal network, per-daemon CA, per-container token,\n `network-policy@1`.\n3. `credential@1`: API-key bindings, sentinel rendering, inject rules.\n4. Harness `Runner`: container create with worktree, volumes, lifecycle\n hooks and the mounted `archie-agent`; `agent-sessions@1` invocation;\n worktree checks for git, protected paths and read-only; budget and\n cancellation.\n5. Claude Code output adapter; `archie-agent mcp`; gate-and-resume loop.\n6. Kit profiles, runner selection from the stage's profile, and definition\n validation.\n7. OAuth bindings as org secrets: token-endpoint interception, encrypted\n storage, per-binding concurrency; dashboard setup terminal.\n8. Output adapters for Codex, Pi, OMP and GitHub Copilot CLI.\n\n## Verification\n\n- The same workflow definition completes on `builtin` and on the Claude Code\n Kit with the same `Result` shape and captures.\n- After `/login` in the setup terminal, the container's credential file holds\n only sentinels, the State Store holds the encrypted token, and a task run\n authenticates.\n- A real API key or OAuth token never appears in the container environment,\n filesystem, worktree, task log or event stream.\n- A request to a host outside the Kit's runtime allow list fails, including a\n direct connection that bypasses the proxy settings.\n- A harness instructed to `git commit` fails its step, and the task branch is\n unchanged.\n- A harness edit to a protected test file fails the step in a TDD fix stage.\n- A read-only feasibility stage that writes a file fails.\n- A file a run writes into a Kit-managed path such as the CLI's settings file\n is gone on the next execution.\n- A Kit requiring an unsupported capability is refused at launch with the\n capability named.\n- A stage with a failing gate resumes the same session with the gate output,\n then succeeds or exhausts its iterations.\n- Two tasks sharing an OAuth binding with `max_concurrent = 1` run one at a\n time; the second waits as `pending`.\n- Stopping a run kills the harness process and removes the container.\n- A harness invocation cannot read the worker's NATS or State Store\n credential from its environment, its files or `/proc`.\n- A run fanning out to many agent invocations uses one container.\n- A Kit profile in org A cannot be selected, and its binding cannot be\n resolved, by a workflow in org B.\n- A harness run whose identity is not granted a Kit's required credential is\n refused at launch; the proxy never injects a secret outside the run\n credential.\n- The firewall investigation example runs unchanged on an image profile with\n direct network access.\n" }, { "url": "/dev/prds/identity-decision/", diff --git a/docs/prds/external-agent-harness.md b/docs/prds/external-agent-harness.md index 6f042bc05..1028c5f86 100644 --- a/docs/prds/external-agent-harness.md +++ b/docs/prds/external-agent-harness.md @@ -85,6 +85,19 @@ ai-sdk agent loop for an image profile, the harness runner for a Kit profile. Image profiles, and every workflow already written against them, are unchanged. A Kit profile named by no workflow is a validation error. +A stage naming a different profile than its workflow's is a separate run, +not a mid-container runner switch: a Kit task runs in one container +provisioned for one profile (Container layout), so a stage that needs a +different one is its own callee, started the way `workflow.call` already +starts one (`docs/prds/event-automation.md` "Workflows call workflows"), +with its own agent profile resolved off its own task row. This needs no +mechanism beyond `workflow.call` plus per-task profile resolution +(`daemon.pinTaskProfile`), both of which already treat every task's +profile independently of any caller's -- see +`TestWorkflowCallerConformance` (staterpc) for the callee's independent +`Workflow` field and `TestWorkflowCallGivesACalleeItsOwnProfile` (daemon) +for the Kit-vs-image runner selection that independence produces. + Profiles are org resources in the State Store, so a Kit profile belongs to one org, is granted to its workspaces like any profile, and applies without a restart. diff --git a/internal/daemon/daemon_test.go b/internal/daemon/daemon_test.go index d34fecaef..8700e432b 100644 --- a/internal/daemon/daemon_test.go +++ b/internal/daemon/daemon_test.go @@ -2353,6 +2353,56 @@ func TestRunViaAgentCarriesTheWorkflowProfile(t *testing.T) { } } +// TestWorkflowCallGivesACalleeItsOwnProfile is the harness PRD's "a stage may +// name a different profile" (docs/prds/external-agent-harness.md, Selection): +// there is no mid-container runner switch, and none is built here. A stage +// wanting a different profile -- a Kit harness where the rest of the workflow +// runs on the built-in loop -- is its own callee workflow, started the way +// workflow.call already starts one (StartCall), with its own agent profile +// resolved independently by pinTaskProfile off the callee's own task row. +// TestWorkflowCallerConformance (staterpc) already proves the callee's +// Workflow field is independent of the caller's; this proves that +// independence is what makes Kit-vs-image runner selection independent too. +func TestWorkflowCallGivesACalleeItsOwnProfile(t *testing.T) { + d, s, _ := daemonWithNATS(t) + cfg := d.Cfg.Get() + cfg.Containers.Profiles = map[string]config.AgentProfile{ + "net": {Image: "agent-net:1"}, + "contain": {Kit: []string{"contain-kit@sha256:ab"}, Adapter: agentexec.AdapterClaudeCode}, + } + d.Cfg.Set(cfg) + d.WorkflowDefinitions = &workflowDefinitionsStub{collection: workflow.WorkflowDefinitionCollection{Definitions: []workflow.WorkflowDefinitionEntry{ + {ID: "investigate", YAML: "id: investigate\nprofile: net\nsteps:\n - type: implement.prepare\n"}, + {ID: "contain", YAML: "id: contain\nrepository: none\nprofile: contain\nsteps:\n - type: agent.run\n settings: {mission: contain it}\n"}, + }}, version: 1} + ctx := context.Background() + + if _, err := s.EnqueueIssue(ctx, "acme", "widget", 41, "t", "b", "", ""); err != nil { + t.Fatal(err) + } + caller, err := s.ClaimNext(ctx) + if err != nil || caller == nil { + t.Fatalf("claim caller: (%v, %v)", caller, err) + } + caller.Workflow = "investigate" + + // Exactly the call a workflow.call step makes (workflow_call.go's + // runWorkflowCall -> tc.Calls.StartCall), not a hand-rolled shortcut. + callee, err := s.StartCall(ctx, caller.ID, "contain", nil) + if err != nil || callee == nil { + t.Fatalf("StartCall: (%+v, %v)", callee, err) + } + + callerProfile, ok := d.pinTaskProfile(ctx, caller) + if !ok || callerProfile.IsKit() { + t.Fatalf("caller profile = %+v, %v; want a non-Kit profile", callerProfile, ok) + } + calleeProfile, ok := d.pinTaskProfile(ctx, callee) + if !ok || !calleeProfile.IsKit() || calleeProfile.Adapter != agentexec.AdapterClaudeCode { + t.Fatalf("callee profile = %+v, %v; want the Kit profile its own workflow names", calleeProfile, ok) + } +} + // A container that dies mid-run (max-uptime reaper, OOM, crash) never answers // the taskrun request. The run must end with the task parked, not left // running with the worker blocked on a reply that cannot come. From 9e4e15dafb2d3dbf67e50b3eee87dfc24f45acdf Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Sun, 27 Sep 2026 05:20:24 +1000 Subject: [PATCH 5/5] feat(harness): declare and enforce a workflow's harness needs at dispatch docs/prds/external-agent-harness.md ("Contract"): workflow definition validation must reject a stage whose needs the selected harness cannot meet -- capture tools without an adapter, or a gate retry without a resume verb. The step vocabulary had no static way to declare either. Added task.WorkflowInterface.Needs{Captures, GateRetries}, parsed and validated (GateRetries >= 0) the same way Inputs/Repository already are. Only a Kit profile is checked against it: an image profile's built-in agent loop always supports both, so Needs constrains only the harness path. Two enforcement points, chosen for where each fact is actually known without a network fetch at save time: - Captures vs adapter is knowable from config alone (profile.Adapter, the agentexec.harnessAdapters table), so daemon.pinTaskProfile checks it right where it already resolves the profile (validateProfileMeetsNeeds), parking the task the same way an unconfigured profile already does. - GateRetries vs the Kit's actual agent-sessions resume verb is only known once the Kit composition is fetched, which kitrun.Launcher.Launch already does -- so kit.ValidateNeeds runs there (new kitrun.Request. GateRetries field, threaded from the workflow's parsed Needs in daemon.runKitTask) rather than inventing an image-fetching workflow-save validator. Deliberately NOT built: "a Kit profile named by no workflow is a validation error" (external-agent-harness.md "Selection"). Read literally ("a Kit profile [that is] named by no workflow"), this is a cross-resource check -- an agent-profiles entry unreferenced by anything in workflow-definitions -- and no control-plane Definition validator can see another resource today (Definition.Validate is a pure []byte->error function by design, matching every existing resource kind). Building that crossing is a real, separate piece of infrastructure with its own ordering questions (does defining a Kit profile before its workflow now fail?), not a two-line addition, so it is left for a follow-on rather than bolted on here. Also fixes a test bug caught by rerunning with a short -timeout per instruction: TestRunKitTaskThreadsGateRetriesToTheLauncher's fake NATS subscriber never responded, so runKitTask's call into runViaAgent blocked forever waiting for a reply bounded by a zero (unconfigured) wall-clock budget. Fixed by responding, matching the sibling test's pattern. --- internal/daemon/daemon.go | 22 +++- internal/daemon/daemon_test.go | 101 ++++++++++++++++++ internal/daemon/kit_task.go | 21 +++- internal/domain/workflow/task/interface.go | 22 ++++ .../domain/workflow/task/interface_test.go | 14 +++ internal/infrastructure/kit/kit.go | 13 +++ internal/infrastructure/kit/kit_test.go | 45 ++++++++ internal/infrastructure/kitrun/launcher.go | 9 ++ 8 files changed, 241 insertions(+), 6 deletions(-) diff --git a/internal/daemon/daemon.go b/internal/daemon/daemon.go index 94d52505f..0adee72e3 100644 --- a/internal/daemon/daemon.go +++ b/internal/daemon/daemon.go @@ -1757,7 +1757,9 @@ func (d *Daemon) pinTaskProfile(ctx context.Context, task *workflow.Task) (confi if err == nil { var profile config.AgentProfile if profile, err = d.configFor(task).Containers.Profile(iface.Profile); err == nil { - return profile, true + if err = validateProfileMeetsNeeds(profile, iface.Needs); err == nil { + return profile, true + } } } d.Log.Error("agent profile unavailable", "task", task.ID, "err", err) @@ -1765,6 +1767,24 @@ func (d *Daemon) pinTaskProfile(ctx context.Context, task *workflow.Task) (confi return config.AgentProfile{}, false } +// validateProfileMeetsNeeds rejects a Kit profile whose harness cannot meet +// what the workflow declares it needs (docs/prds/external-agent-harness.md, +// "Contract"): a workflow needing captures but naming a profile whose Kit CLI +// serves none (no adapter, or one with no MCP config to register archie-agent +// mcp against -- e.g. Codex, Pi, OMP per agentexec.harnessAdapters). An image +// profile is never checked: the built-in agent loop always supports both +// captures and gate retries, so Needs constrains only the harness path. +func validateProfileMeetsNeeds(profile config.AgentProfile, needs workflowtask.WorkflowNeeds) error { + if !profile.IsKit() || !needs.Captures { + return nil + } + adapter, ok := agentexec.LookupHarnessAdapter(profile.Adapter) + if !ok || len(adapter.MCPConfig) == 0 { + return fmt.Errorf("needs.captures is set, but profile adapter %q serves no capture tools", profile.Adapter) + } + return nil +} + // publicationGrant issues the capability to publish the task's branch. A task // with no repository has nothing to publish and gets none. func (d *Daemon) publicationGrant(ctx context.Context, task *workflow.Task) (string, func(), bool) { diff --git a/internal/daemon/daemon_test.go b/internal/daemon/daemon_test.go index 8700e432b..81f6a88b1 100644 --- a/internal/daemon/daemon_test.go +++ b/internal/daemon/daemon_test.go @@ -2353,6 +2353,65 @@ func TestRunViaAgentCarriesTheWorkflowProfile(t *testing.T) { } } +// TestPinTaskProfileRefusesCapturesTheHarnessCannotServe is the harness PRD's +// (Contract) "workflow definition validation rejects... a stage whose needs +// the selected harness cannot meet: capture tools without an adapter". A Kit +// profile's own adapter -- not the workflow -- decides whether captures are +// servable, so a workflow that needs them but names a profile whose CLI +// serves no capture tools (empty MCPConfig, e.g. Codex/Pi/OMP) must be +// refused rather than silently running with no way to return its result. +func TestPinTaskProfileRefusesCapturesTheHarnessCannotServe(t *testing.T) { + d, s, _ := daemonWithNATS(t) + cfg := d.Cfg.Get() + cfg.Containers.Profiles = map[string]config.AgentProfile{ + "serves-captures": {Kit: []string{"kit@sha256:ab"}, Adapter: agentexec.AdapterClaudeCode}, + "no-captures": {Kit: []string{"kit@sha256:ab"}, Adapter: agentexec.AdapterCodex}, + "no-adapter": {Kit: []string{"kit@sha256:ab"}}, + } + d.Cfg.Set(cfg) + d.WorkflowDefinitions = &workflowDefinitionsStub{collection: workflow.WorkflowDefinitionCollection{Definitions: []workflow.WorkflowDefinitionEntry{ + {ID: "needs-captures-served", YAML: "id: needs-captures-served\nrepository: none\nprofile: serves-captures\nneeds: {captures: true}\nsteps:\n - type: agent.run\n settings: {mission: go}\n"}, + {ID: "needs-captures-codex", YAML: "id: needs-captures-codex\nrepository: none\nprofile: no-captures\nneeds: {captures: true}\nsteps:\n - type: agent.run\n settings: {mission: go}\n"}, + {ID: "needs-captures-bare", YAML: "id: needs-captures-bare\nrepository: none\nprofile: no-adapter\nneeds: {captures: true}\nsteps:\n - type: agent.run\n settings: {mission: go}\n"}, + }}, version: 1} + ctx := context.Background() + + claim := func(number int, wf string) *workflow.Task { + t.Helper() + if _, err := s.EnqueueIssue(ctx, "acme", "widget", number, "t", "b", "", ""); err != nil { + t.Fatal(err) + } + task, err := s.ClaimNext(ctx) + if err != nil || task == nil { + t.Fatalf("claim: (%v, %v)", task, err) + } + task.Workflow = wf + return task + } + + served := claim(51, "needs-captures-served") + if _, ok := d.pinTaskProfile(ctx, served); !ok { + t.Fatal("a Kit profile whose adapter serves captures was refused") + } + + for _, tt := range []struct { + number int + workflow string + }{ + {52, "needs-captures-codex"}, + {53, "needs-captures-bare"}, + } { + task := claim(tt.number, tt.workflow) + if _, ok := d.pinTaskProfile(ctx, task); ok { + t.Fatalf("%s: a workflow needing captures was not refused by a profile that cannot serve them", tt.workflow) + } + got, err := s.TaskByID(ctx, task.ID) + if err != nil || got.Status != workflow.StatusParked || !strings.Contains(got.ParkReason, "captures") { + t.Fatalf("%s: task = %+v, %v; want parked naming the unmet captures need", tt.workflow, got, err) + } + } +} + // TestWorkflowCallGivesACalleeItsOwnProfile is the harness PRD's "a stage may // name a different profile" (docs/prds/external-agent-harness.md, Selection): // there is no mid-container runner switch, and none is built here. A stage @@ -2571,3 +2630,45 @@ func TestKitProfileRunsTheTaskOnItsHarness(t *testing.T) { t.Fatalf("released %v, removed %v; want the run released and its volumes removed", launcher.released, launcher.removed) } } + +// TestRunKitTaskThreadsGateRetriesToTheLauncher: KitLauncher.Launch is where +// the Kit's actual agent-sessions capability is known (it composes the Kit), +// so that is where docs/prds/external-agent-harness.md's "a gate retry +// without a resume verb" refusal has to run (kit.ValidateNeeds, wired in +// kitrun.Launcher.Launch). This proves runKitTask carries the workflow's +// declared retry budget there rather than dropping it. +func TestRunKitTaskThreadsGateRetriesToTheLauncher(t *testing.T) { + d, s, busClient := daemonWithNATS(t) + launcher := &fakeKitLauncher{} + d.KitLauncher = launcher + d.ConnectedNATS.URL = "nats://172.17.0.1:4222" + ctx := context.Background() + if _, err := s.EnqueueIssue(ctx, "acme", "widget", 32, "t", "b", "", ""); err != nil { + t.Fatal(err) + } + task, err := s.ClaimNext(ctx) + if err != nil || task == nil { + t.Fatalf("claim: (%v, %v)", task, err) + } + task.WorkflowDefinitionYAML = "id: contain\nrepository: none\nneeds: {gate_retries: 4}\nsteps:\n - type: agent.run\n settings: {mission: go}\n" + // runKitTask calls through to runViaAgent after Launch, which blocks on a + // NATS reply bounded by the task wall-clock budget (zero here, i.e. no + // bound at all) -- a handler that never responds hangs the daemon + // goroutine forever rather than timing out, so this must answer even + // though the assertion below only cares about what Launch already saw. + sub, err := mustCoreConn(t, busClient).Subscribe(agentnats.SubjectForTask(task.ID), func(msg *natsio.Msg) { + data, _ := json.Marshal(taskrun.Response{Status: workflow.StatusPROpen}) + _ = msg.Respond(data) + }) + if err != nil { + t.Fatalf("subscribe: %v", err) + } + t.Cleanup(func() { _ = sub.Unsubscribe() }) + + d.runKitTask(ctx, task, config.Repo{Owner: "acme", Name: "widget", Base: "main"}, t.TempDir(), + config.AgentProfile{Kit: []string{"kit@sha256:ab"}, Adapter: agentexec.AdapterClaudeCode}) + + if launcher.got.GateRetries != 4 { + t.Fatalf("launch request GateRetries = %d, want the workflow's declared 4", launcher.got.GateRetries) + } +} diff --git a/internal/daemon/kit_task.go b/internal/daemon/kit_task.go index 53afb1178..9b7bbc922 100644 --- a/internal/daemon/kit_task.go +++ b/internal/daemon/kit_task.go @@ -8,6 +8,7 @@ import ( "github.com/samcharles93/archie-core/internal/config" "github.com/samcharles93/archie-core/internal/domain/workflow" + workflowtask "github.com/samcharles93/archie-core/internal/domain/workflow/task" "github.com/samcharles93/archie-core/internal/infrastructure/kit" "github.com/samcharles93/archie-core/internal/infrastructure/kitrun" "github.com/samcharles93/archie-core/internal/taskstate" @@ -51,12 +52,22 @@ func (d *Daemon) runKitTask(ctx context.Context, task *workflow.Task, repo confi park("kit worker environment", err) return } + // The interface is reparsed rather than threaded through pinTaskProfile's + // return: task.WorkflowDefinitionYAML is already pinned by the time this + // runs, parsing it is pure and cheap, and pinTaskProfile's signature stays + // unchanged for its other callers. + iface, err := workflowtask.ParseWorkflowInterface(task.WorkflowDefinitionYAML) + if err != nil { + park("kit workflow interface", err) + return + } run, err := d.KitLauncher.Launch(ctx, kitrun.Request{ - Execution: fmt.Sprintf("task-%d", task.ID), - Kit: profile.Kit, - Adapter: profile.Adapter, - WorkDir: workDir, - WorkerEnv: env, + Execution: fmt.Sprintf("task-%d", task.ID), + Kit: profile.Kit, + Adapter: profile.Adapter, + WorkDir: workDir, + WorkerEnv: env, + GateRetries: iface.Needs.GateRetries, }) if err != nil { park("kit launch failed", err) diff --git a/internal/domain/workflow/task/interface.go b/internal/domain/workflow/task/interface.go index 3de3e16d8..651d67882 100644 --- a/internal/domain/workflow/task/interface.go +++ b/internal/domain/workflow/task/interface.go @@ -42,6 +42,25 @@ type WorkflowInterface struct { // Profile names a [containers.profiles] entry. It is resolved when a task // is dispatched, not when the workflow is saved. Profile string `yaml:"profile,omitempty" json:"profile,omitempty"` + // Needs declares what this workflow's agent stages require of the + // profile they run under -- checked against the profile's actual + // capabilities before dispatch (docs/prds/external-agent-harness.md, + // "Contract"): a stage that returns structured output needs a harness + // with a capture-tools-capable output adapter, and a gated stage that + // may retry needs the Kit's agent-sessions resume verb. Only a Kit + // profile is checked against it -- an image profile's built-in agent + // loop always supports both. + Needs WorkflowNeeds `yaml:"needs" json:"needs"` +} + +// WorkflowNeeds is WorkflowInterface's declared harness requirements. +type WorkflowNeeds struct { + // Captures declares that a stage returns structured output through + // capture tools. + Captures bool `yaml:"captures,omitempty" json:"captures,omitempty"` + // GateRetries is the largest gate-retry budget any stage declares. Zero + // means no stage gates its result, so no resume capability is needed. + GateRetries int `yaml:"gate_retries,omitempty" json:"gate_retries,omitempty"` } var ( @@ -75,6 +94,9 @@ func (w WorkflowInterface) Validate() error { return fmt.Errorf("workflow input %q type %q must be one of %s", name, spec.Type, strings.Join(inputTypes, ", ")) } } + if w.Needs.GateRetries < 0 { + return fmt.Errorf("workflow needs.gate_retries must not be negative") + } return nil } diff --git a/internal/domain/workflow/task/interface_test.go b/internal/domain/workflow/task/interface_test.go index 545720ef7..4a7f3c44f 100644 --- a/internal/domain/workflow/task/interface_test.go +++ b/internal/domain/workflow/task/interface_test.go @@ -18,6 +18,7 @@ func TestParseWorkflowInterface(t *testing.T) { {name: "unknown mode", src: "id: a\nrepository: sometimes\n", wantErr: "must be none, optional or required"}, {name: "unknown input type", src: "id: a\ninputs:\n ip: {type: ipv4}\n", wantErr: `type "ipv4"`}, {name: "malformed input name", src: "id: a\ninputs:\n src-ip: {type: string}\n", wantErr: `input "src-ip"`}, + {name: "negative gate_retries", src: "id: a\nneeds: {gate_retries: -1}\n", wantErr: "gate_retries must not be negative"}, } for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { @@ -38,6 +39,19 @@ func TestParseWorkflowInterface(t *testing.T) { } } +// TestParseWorkflowInterfaceNeeds pins the declared-needs vocabulary +// (docs/prds/external-agent-harness.md, "Contract"): a stage's requirements +// of its harness are static, readable metadata, not derived at run time. +func TestParseWorkflowInterfaceNeeds(t *testing.T) { + w, err := ParseWorkflowInterface("id: a\nprofile: contain\nneeds: {captures: true, gate_retries: 3}\n") + if err != nil { + t.Fatal(err) + } + if !w.Needs.Captures || w.Needs.GateRetries != 3 { + t.Fatalf("Needs = %+v, want {Captures:true GateRetries:3}", w.Needs) + } +} + func TestCheckInputs(t *testing.T) { w := WorkflowInterface{Inputs: map[string]InputSpec{ "src_ip": {Type: "string", Required: true}, diff --git a/internal/infrastructure/kit/kit.go b/internal/infrastructure/kit/kit.go index c9b9604a3..aba1b3b72 100644 --- a/internal/infrastructure/kit/kit.go +++ b/internal/infrastructure/kit/kit.go @@ -161,6 +161,19 @@ func FromMerge(merged *spec.MergeResult) (*Plan, error) { return plan, nil } +// ValidateNeeds rejects a Plan that cannot meet what the workflow's stages +// declared they need (docs/prds/external-agent-harness.md, "Contract"): a +// gate that may retry needs the Kit's agent-sessions resume verb, because +// archie resumes the session with the gate's output rather than starting +// over. gateRetries is zero for a workflow with no gated stage, which no +// Kit composition can fail to meet. +func ValidateNeeds(plan *Plan, gateRetries int) error { + if gateRetries > 0 && (plan.Sessions == nil || len(plan.Sessions.Resume) == 0) { + return fmt.Errorf("needs.gate_retries is %d, but the kit declares no %s resume verb to retry with", gateRetries, typeAgentSessions) + } + return nil +} + func refusalReason(c spec.Capability) (string, error) { if !supported[c.Type] { return "not provided by archie", nil diff --git a/internal/infrastructure/kit/kit_test.go b/internal/infrastructure/kit/kit_test.go index 9623c105a..2fa71912b 100644 --- a/internal/infrastructure/kit/kit_test.go +++ b/internal/infrastructure/kit/kit_test.go @@ -208,6 +208,51 @@ func TestCompose(t *testing.T) { } } +// TestValidateNeeds pins the harness PRD's "a gate retry without a resume +// verb" refusal (Contract): archie resumes the harness's own session with the +// gate's output rather than starting a fresh one, so a gated stage's retry +// budget is unmeetable by a Kit whose agent-sessions capability names no +// resume verb. +func TestValidateNeeds(t *testing.T) { + promptOnly := descriptor(t, spec.KindWorkload, ` + - type: com.docker.sandbox/agent-sessions@1 + config: + prompt: [-p, "{{.Prompt}}"]`) + withResume := descriptor(t, spec.KindWorkload, sessions) + + tests := []struct { + name string + descriptor *spec.Descriptor + gateRetries int + wantErr bool + }{ + {"no gated stage, no resume verb", promptOnly, 0, false}, + {"gated stage, no resume verb", promptOnly, 2, true}, + {"gated stage, a resume verb", withResume, 2, false}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + plan, err := Admit(tt.descriptor) + if err != nil { + t.Fatalf("Admit: %v", err) + } + sessions, err := spec.AgentSessionsOf(plan.Capabilities) + if err != nil { + t.Fatalf("AgentSessionsOf: %v", err) + } + plan.Sessions = sessions + + err = ValidateNeeds(plan, tt.gateRetries) + if tt.wantErr && err == nil { + t.Fatal("ValidateNeeds accepted a gate retry budget the kit cannot resume") + } + if !tt.wantErr && err != nil { + t.Fatalf("ValidateNeeds: %v", err) + } + }) + } +} + func TestDecodePublished(t *testing.T) { published := "schemaVersion: \"3\"\nkind: workload\ncapabilities:" + sessions + "\n" tests := []struct { diff --git a/internal/infrastructure/kitrun/launcher.go b/internal/infrastructure/kitrun/launcher.go index f3f9f084a..d3cd0c97a 100644 --- a/internal/infrastructure/kitrun/launcher.go +++ b/internal/infrastructure/kitrun/launcher.go @@ -49,6 +49,12 @@ type Request struct { Adapter string WorkDir string WorkerEnv []string + // GateRetries is the workflow's declared gate-retry budget + // (task.WorkflowNeeds.GateRetries); zero means no stage gates its + // result. A composition with no agent-sessions resume verb cannot meet + // a positive one, and Launch refuses it rather than starting a + // container no gate failure could ever resume. + GateRetries int } // Run is a started Kit task. @@ -78,6 +84,9 @@ func (l *Launcher) Launch(ctx context.Context, req Request) (*Run, error) { if err != nil { return nil, err } + if err := kit.ValidateNeeds(plan, req.GateRetries); err != nil { + return nil, err + } network, err := spec.NetworkPolicyOf(plan.Capabilities) if err != nil { return nil, err