feat(run): add runtime agent resolution from config (ADR 0058 Phase 3)

When agents are registered in config.yaml, `fullsend run` now resolves
them at runtime instead of requiring on-disk wrapper harnesses:

- URL sources are fetched, integrity-verified, and cached via the
  existing ADR 0038 fetch infrastructure
- Local path sources are resolved relative to the fullsend directory
- Scaffold fallback is preserved when no config entry matches

The harness wrapper layer now skips generating wrappers for
config-driven agents since they are resolved at runtime.

Signed-off-by: Greg Allen <gallen@redhat.com>
Signed-off-by: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Greg Allen <gallen@redhat.com>

Author: ggallen

internal/cli/admin.go

@@ -1852,7 +1852,7 @@ func buildLayerStack(
 	return layers.NewStack(
 		layers.NewConfigRepoLayer(org, client, cfg, printer, privateRepo),
 		workflowsLayer(ctx, org, client, printer, user, version, vendor, vendorCollect, direct),
-		layers.NewHarnessWrappersLayer(org, client, printer, agentCreds, commitSHA),
+		layers.NewHarnessWrappersLayer(org, client, printer, agentCreds, commitSHA, configAgentNames(cfg.Agents)),
 		vendorLayer(org, client, printer, vendor, vendorFn, vendorCollect, analyzeFullsendSource),
 		layers.NewSecretsLayer(org, client, agentCreds, printer).WithOIDCMode(),
 		layers.NewInferenceLayer(org, client, inferenceProvider, printer),

internal/cli/admin_test.go

@@ -1278,7 +1278,7 @@ func TestCheckInstallScopes_SyncWithLayers(t *testing.T) {
 	stack := layers.NewStack(
 		layers.NewConfigRepoLayer("test-org", nil, emptyCfg, ui.New(&discardWriter{}), false),
 		layers.NewWorkflowsLayer("test-org", nil, ui.New(&discardWriter{}), "", "test-version", false),
-		layers.NewHarnessWrappersLayer("test-org", nil, ui.New(&discardWriter{}), nil, "dev"),
+		layers.NewHarnessWrappersLayer("test-org", nil, ui.New(&discardWriter{}), nil, "dev", nil),
 		layers.NewSecretsLayer("test-org", nil, nil, ui.New(&discardWriter{})),
 		layers.NewInferenceLayer("test-org", nil, nil, ui.New(&discardWriter{})),
 		layers.NewOIDCDispatchLayer("test-org", nil, nil, nil, ui.New(&discardWriter{})),

internal/cli/orgconfig.go

@@ -8,6 +8,15 @@ import (
 	"github.com/fullsend-ai/fullsend/internal/ui"
 )
 
+// configAgentNames extracts derived names from a list of agent entries.
+func configAgentNames(agents []config.AgentEntry) []string {
+	names := make([]string, len(agents))
+	for i, a := range agents {
+		names[i] = a.DerivedName()
+	}
+	return names
+}
+
 // tryLoadOrgConfig attempts to load org config from the given path.
 // Returns nil without error when the file is absent (best-effort).
 // Logs warnings via printer for non-ENOENT read errors and parse errors.

internal/cli/run.go

@@ -171,12 +171,7 @@ func runAgent(ctx context.Context, agentName, fullsendDir, outputBase, targetRep
 	}
 
 	// 1. Resolve and load harness.
-	harnessPath, err := resolveHarnessPath(absFullsendDir, agentName, printer)
-	if err != nil {
-		return err
-	}
 	harnessStart := time.Now()
-	printer.StepStart("Loading harness: " + harnessPath)
 
 	forgePlatform, err := detectForgePlatform(forgeFlag)
 	if err != nil {
@@ -188,50 +183,62 @@ func runAgent(ctx context.Context, agentName, fullsendDir, outputBase, targetRep
 	policy.Offline = rFlags.offline
 
 	// Best-effort org config loading — provides the allowlist for base
-	// harness fetching. If the file is missing or unparseable we proceed
-	// without it; HasURLReferences will enforce its presence later if needed.
+	// harness fetching and the agent registry for config-driven resolution.
+	// If the file is missing or unparseable we proceed without it;
+	// HasURLReferences will enforce its presence later if needed.
 	orgConfigPath := filepath.Join(absFullsendDir, "config.yaml")
 	orgCfg := tryLoadOrgConfig(orgConfigPath, printer)
 	var orgAllowlist []string
 	if orgCfg != nil {
 		orgAllowlist = orgCfg.AllowedRemoteResources
 	}
 
-	// If the harness has a URL base and org config failed to load,
-	// load it strictly now so LoadWithBase gets a proper error path
-	// rather than an unhelpful "URL base requires allowed_remote_resources".
-	if orgCfg == nil {
-		if rawH, rawErr := harness.LoadRaw(harnessPath); rawErr == nil && rawH.Base != "" && harness.IsURL(rawH.Base) {
-			var err error
-			orgCfg, err = requireOrgConfig(orgConfigPath, printer)
-			if err != nil {
-				return err
-			}
-			orgAllowlist = orgCfg.AllowedRemoteResources
-		}
-	}
-
 	var composeForgeClient forge.Client
 	if rFlags.forgeClient != nil {
 		composeForgeClient = rFlags.forgeClient
 	} else if token, tokenErr := resolveToken(); tokenErr == nil {
 		composeForgeClient = gh.New(token)
 	}
 
-	h, baseDeps, err := harness.LoadWithBase(ctx, harnessPath, harness.ComposeOpts{
+	composeOpts := harness.ComposeOpts{
 		WorkspaceRoot: absFullsendDir,
 		FetchPolicy:   policy,
 		AuditLogPath:  filepath.Join(absFullsendDir, ".fullsend-cache", "fetch-audit.jsonl"),
 		ForgePlatform: forgePlatform,
 		OrgAllowlist:  orgAllowlist,
 		ForgeClient:   composeForgeClient,
-	})
+	}
+
+	// Resolve agent source: config agents take precedence over disk harnesses.
+	harnessPath, fetchDeps, err := resolveAgentSource(ctx, absFullsendDir, agentName, orgCfg, composeOpts, printer)
+	if err != nil {
+		return err
+	}
+
+	printer.StepStart("Loading harness: " + harnessPath)
+
+	// If the harness has a URL base and org config failed to load,
+	// load it strictly now so LoadWithBase gets a proper error path
+	// rather than an unhelpful "URL base requires allowed_remote_resources".
+	if orgCfg == nil {
+		if rawH, rawErr := harness.LoadRaw(harnessPath); rawErr == nil && rawH.Base != "" && harness.IsURL(rawH.Base) {
+			var err error
+			orgCfg, err = requireOrgConfig(orgConfigPath, printer)
+			if err != nil {
+				return err
+			}
+			composeOpts.OrgAllowlist = orgCfg.AllowedRemoteResources
+		}
+	}
+
+	h, baseDeps, err := harness.LoadWithBase(ctx, harnessPath, composeOpts)
 	if err != nil {
 		printer.StepFail("Failed to load harness")
 		return fmt.Errorf("loading harness: %w", err)
 	}
 
-	for _, dep := range baseDeps {
+	allDeps := append(fetchDeps, baseDeps...)
+	for _, dep := range allDeps {
 		if dep.CacheHit {
 			printer.StepInfo(fmt.Sprintf("Base: %s (cache hit)", dep.URL))
 		} else {
@@ -2344,3 +2351,49 @@ func validateRepoNames(repos []string) error {
 	}
 	return nil
 }
+
+// resolveAgentSource resolves the harness path for an agent, checking
+// config-registered agents before falling back to disk-based lookup.
+// Returns the local filesystem path to the harness (cached for URL sources)
+// and any fetch dependencies from URL-based agent resolution.
+func resolveAgentSource(ctx context.Context, fullsendDir, agentName string, orgCfg *config.OrgConfig, composeOpts harness.ComposeOpts, printer *ui.Printer) (string, []harness.Dependency, error) {
+	if orgCfg == nil || len(orgCfg.Agents) == 0 {
+		path, err := resolveHarnessPath(fullsendDir, agentName, printer)
+		return path, nil, err
+	}
+
+	sha := commitSHA
+	if sha == "dev" {
+		sha = ""
+	}
+	scaffoldNames, _ := scaffold.HarnessNames()
+
+	merged, err := config.MergedAgents(scaffoldNames, sha, orgCfg.Agents, scaffold.HarnessBaseURLWithHash)
+	if err != nil {
+		return "", nil, fmt.Errorf("building merged agent set: %w", err)
+	}
+
+	agent := config.LookupMergedAgent(merged, agentName)
+	if agent == nil || !agent.IsConfig {
+		path, err := resolveHarnessPath(fullsendDir, agentName, printer)
+		return path, nil, err
+	}
+
+	if harness.IsURL(agent.Source) {
+		printer.StepStart(fmt.Sprintf("Fetching agent harness: %s", agent.Name))
+		localPath, dep, err := harness.FetchAgentHarness(ctx, agent.Source, composeOpts)
+		if err != nil {
+			printer.StepFail("Failed to fetch agent harness")
+			return "", nil, fmt.Errorf("resolving config agent %s: %w", agent.Name, err)
+		}
+		printer.StepDone(fmt.Sprintf("Agent %s resolved from config (URL)", agent.Name))
+		return localPath, []harness.Dependency{dep}, nil
+	}
+
+	localPath := filepath.Join(fullsendDir, agent.Source)
+	if _, err := os.Stat(localPath); err != nil {
+		return "", nil, fmt.Errorf("config agent %s: local path %s: %w", agent.Name, agent.Source, err)
+	}
+	printer.StepDone(fmt.Sprintf("Agent %s resolved from config (local path)", agent.Name))
+	return localPath, nil, nil
+}

internal/cli/run_test.go

@@ -21,6 +21,7 @@ import (
 	"github.com/stretchr/testify/require"
 
 	"github.com/fullsend-ai/fullsend/internal/binary"
+	"github.com/fullsend-ai/fullsend/internal/config"
 	"github.com/fullsend-ai/fullsend/internal/fetch"
 	"github.com/fullsend-ai/fullsend/internal/fetchsvc"
 	"github.com/fullsend-ai/fullsend/internal/forge"
@@ -478,6 +479,209 @@ func TestRunCommand_HasEnvFileFlag(t *testing.T) {
 	assert.Equal(t, []string{"/tmp/a.env", "/tmp/b.env"}, val)
 }
 
+func TestRunAgent_ConfigAgentLocalPath(t *testing.T) {
+	dir := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "harness"), 0o755))
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "agents"), 0o755))
+
+	require.NoError(t, os.WriteFile(
+		filepath.Join(dir, "agents", "custom.md"),
+		[]byte("You are a custom agent."),
+		0o644,
+	))
+	require.NoError(t, os.WriteFile(
+		filepath.Join(dir, "harness", "custom.yaml"),
+		[]byte("agent: agents/custom.md\nrole: test\n"),
+		0o644,
+	))
+	require.NoError(t, os.WriteFile(
+		filepath.Join(dir, "config.yaml"),
+		[]byte("agents:\n  - harness/custom.yaml\nallowed_remote_resources:\n  - \"https://example.com/\"\n"),
+		0o644,
+	))
+
+	rFlags := resolveFlags{maxDepth: 10, maxResources: 50}
+	printer := ui.New(io.Discard)
+	repoDir := t.TempDir()
+	err := runAgent(context.Background(), "custom", dir, "", repoDir, "", nil, false, "", "", rFlags, statusOpts{}, printer, false)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "openshell")
+}
+
+func TestRunAgent_ConfigAgentURL(t *testing.T) {
+	harnessContent := []byte("agent: agents/remote.md\nrole: test\n")
+	harnessHash := fetch.ComputeSHA256(harnessContent)
+
+	srv, policy := newLockTestServer(t, map[string][]byte{
+		"/harness/triage.yaml": harnessContent,
+	})
+
+	dir := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "harness"), 0o755))
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "agents"), 0o755))
+
+	require.NoError(t, os.WriteFile(
+		filepath.Join(dir, "agents", "remote.md"),
+		[]byte("You are a remote agent."),
+		0o644,
+	))
+	require.NoError(t, os.WriteFile(
+		filepath.Join(dir, "config.yaml"),
+		[]byte(fmt.Sprintf("agents:\n  - \"%s/harness/triage.yaml#sha256=%s\"\nallowed_remote_resources:\n  - \"%s/\"\n", srv.URL, harnessHash, srv.URL)),
+		0o644,
+	))
+
+	fetch.DefaultPolicy = policy
+	defer func() { fetch.DefaultPolicy = fetch.FetchPolicy{} }()
+
+	rFlags := resolveFlags{maxDepth: 10, maxResources: 50}
+	printer := ui.New(io.Discard)
+	repoDir := t.TempDir()
+	err := runAgent(context.Background(), "triage", dir, "", repoDir, "", nil, false, "", "", rFlags, statusOpts{}, printer, false)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "openshell")
+}
+
+func TestRunAgent_ConfigAgentOverridesScaffold(t *testing.T) {
+	// When config has an agent with the same name as a scaffold agent,
+	// the config source is used instead of the scaffold wrapper.
+	dir := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "harness"), 0o755))
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "agents"), 0o755))
+
+	require.NoError(t, os.WriteFile(
+		filepath.Join(dir, "agents", "code.md"),
+		[]byte("You are a custom code agent."),
+		0o644,
+	))
+	// Config-driven local path agent named "code" — should take precedence
+	// over any scaffold "code" harness wrapper.
+	require.NoError(t, os.WriteFile(
+		filepath.Join(dir, "harness", "code.yaml"),
+		[]byte("agent: agents/code.md\nrole: test\n"),
+		0o644,
+	))
+	require.NoError(t, os.WriteFile(
+		filepath.Join(dir, "config.yaml"),
+		[]byte("agents:\n  - harness/code.yaml\nallowed_remote_resources:\n  - \"https://example.com/\"\n"),
+		0o644,
+	))
+
+	rFlags := resolveFlags{maxDepth: 10, maxResources: 50}
+	printer := ui.New(io.Discard)
+	repoDir := t.TempDir()
+	err := runAgent(context.Background(), "code", dir, "", repoDir, "", nil, false, "", "", rFlags, statusOpts{}, printer, false)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "openshell")
+}
+
+func TestRunAgent_ScaffoldFallback(t *testing.T) {
+	// When config has agents but the requested agent is not in config,
+	// fall back to disk-based resolution.
+	dir := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "harness"), 0o755))
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "agents"), 0o755))
+
+	require.NoError(t, os.WriteFile(
+		filepath.Join(dir, "agents", "code.md"),
+		[]byte("You are a coding agent."),
+		0o644,
+	))
+	require.NoError(t, os.WriteFile(
+		filepath.Join(dir, "harness", "code.yaml"),
+		[]byte("agent: agents/code.md\nrole: test\n"),
+		0o644,
+	))
+	// Config has agents but "code" is not among them — should fall back to disk.
+	require.NoError(t, os.WriteFile(
+		filepath.Join(dir, "config.yaml"),
+		[]byte("agents:\n  - harness/other.yaml\nallowed_remote_resources:\n  - \"https://example.com/\"\n"),
+		0o644,
+	))
+
+	rFlags := resolveFlags{maxDepth: 10, maxResources: 50}
+	printer := ui.New(io.Discard)
+	repoDir := t.TempDir()
+	err := runAgent(context.Background(), "code", dir, "", repoDir, "", nil, false, "", "", rFlags, statusOpts{}, printer, false)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "openshell")
+}
+
+func TestRunAgent_UnknownAgentName(t *testing.T) {
+	dir := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "harness"), 0o755))
+
+	// Config has agents but "nonexistent" is not among them, and no file on disk.
+	require.NoError(t, os.WriteFile(
+		filepath.Join(dir, "config.yaml"),
+		[]byte("agents:\n  - harness/other.yaml\nallowed_remote_resources:\n  - \"https://example.com/\"\n"),
+		0o644,
+	))
+
+	rFlags := resolveFlags{maxDepth: 10, maxResources: 50}
+	printer := ui.New(io.Discard)
+	repoDir := t.TempDir()
+	err := runAgent(context.Background(), "nonexistent", dir, "", repoDir, "", nil, false, "", "", rFlags, statusOpts{}, printer, false)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "harness file not found")
+}
+
+func TestResolveAgentSource_NoConfig(t *testing.T) {
+	dir := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "harness"), 0o755))
+	require.NoError(t, os.WriteFile(
+		filepath.Join(dir, "harness", "code.yaml"),
+		[]byte("agent: agents/code.md\nrole: test\n"),
+		0o644,
+	))
+
+	printer := ui.New(io.Discard)
+	path, deps, err := resolveAgentSource(context.Background(), dir, "code", nil, harness.ComposeOpts{}, printer)
+	require.NoError(t, err)
+	assert.Contains(t, path, "code.yaml")
+	assert.Empty(t, deps)
+}
+
+func TestResolveAgentSource_ConfigLocalPath(t *testing.T) {
+	dir := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "harness"), 0o755))
+	require.NoError(t, os.WriteFile(
+		filepath.Join(dir, "harness", "custom.yaml"),
+		[]byte("agent: agents/custom.md\nrole: test\n"),
+		0o644,
+	))
+
+	orgCfg := &config.OrgConfig{
+		Agents: []config.AgentEntry{
+			{Source: "harness/custom.yaml"},
+		},
+		AllowedRemoteResources: []string{"https://example.com/"},
+	}
+
+	printer := ui.New(io.Discard)
+	path, deps, err := resolveAgentSource(context.Background(), dir, "custom", orgCfg, harness.ComposeOpts{}, printer)
+	require.NoError(t, err)
+	assert.Equal(t, filepath.Join(dir, "harness", "custom.yaml"), path)
+	assert.Empty(t, deps)
+}
+
+func TestResolveAgentSource_ConfigLocalPathNotFound(t *testing.T) {
+	dir := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "harness"), 0o755))
+
+	orgCfg := &config.OrgConfig{
+		Agents: []config.AgentEntry{
+			{Source: "harness/missing.yaml"},
+		},
+		AllowedRemoteResources: []string{"https://example.com/"},
+	}
+
+	printer := ui.New(io.Discard)
+	_, _, err := resolveAgentSource(context.Background(), dir, "missing", orgCfg, harness.ComposeOpts{}, printer)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "config agent missing")
+}
+
 func TestApplySandboxImageOverride_Applied(t *testing.T) {
 	t.Setenv("FULLSEND_SANDBOX_IMAGE", "ghcr.io/fullsend-ai/fullsend-sandbox:dev")