feat(cli): add runtime fallback to agents repo for unconfigured agents

When an agent is not registered in config.yaml, resolveAgentSource now
attempts to fetch the latest harness from fullsend-ai/agents before
falling back to the scaffold-embedded harness on disk. This allows
existing fullsend users to transparently use the extracted agents
repository without any config changes.

The fallback resolves the main branch HEAD SHA via the GitHub API,
constructs a pinned URL with integrity hash, and uses the existing
FetchAgentHarness path for full security validation. Only known
first-party agents (triage, code, fix, review, retro, prioritize)
are eligible for fallback. The fallback is skipped in offline mode
or when no git token is available.

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

Author: ggallen

internal/cli/run.go

@@ -49,8 +49,28 @@ const (
 
 	// metricsFile is the filename written to the run directory with behavioral metrics.
 	metricsFile = "metrics.json"
+
+	// Default agents repository for runtime fallback when an agent is not
+	// registered in config. The binary resolves the latest commit SHA from
+	// this repo and fetches the harness dynamically.
+	defaultAgentsRepoOwner  = "fullsend-ai"
+	defaultAgentsRepoName   = "agents"
+	defaultAgentsRepoBranch = "main"
+	agentsRepoURLPrefix     = "https://raw.githubusercontent.com/fullsend-ai/agents/"
 )
 
+// agentsRepoKnownAgents is the set of first-party agents available in the
+// fullsend-ai/agents repository. The fallback only attempts resolution for
+// agents in this set — custom agents are not tried against the agents repo.
+var agentsRepoKnownAgents = map[string]bool{
+	"triage":     true,
+	"code":       true,
+	"fix":        true,
+	"review":     true,
+	"retro":      true,
+	"prioritize": true,
+}
+
 // statusMintToken is the test seam for minting tokens. Shared by both
 // setupStatusNotifier (status comment tokens) and mintAgentToken (agent
 // runtime tokens). Tests that override it affect both paths.
@@ -224,7 +244,7 @@ func runAgent(ctx context.Context, agentName, fullsendDir, outputBase, targetRep
 	}
 
 	// Resolve agent source: config agents take precedence over disk harnesses.
-	harnessPath, fetchDeps, err := resolveAgentSource(ctx, absFullsendDir, agentName, orgCfg, composeOpts, printer)
+	harnessPath, fetchDeps, err := resolveAgentSource(ctx, absFullsendDir, agentName, composeGitToken, orgCfg, composeOpts, printer)
 	if err != nil {
 		return err
 	}
@@ -2556,11 +2576,15 @@ func validateRepoNames(repos []string) error {
 }
 
 // resolveAgentSource resolves the harness path for an agent, checking
-// config-registered agents before falling back to disk-based lookup.
+// config-registered agents first, then falling back to the agents repo
+// (fullsend-ai/agents), then 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) {
+func resolveAgentSource(ctx context.Context, fullsendDir, agentName, gitToken string, orgCfg *config.OrgConfig, composeOpts harness.ComposeOpts, printer *ui.Printer) (string, []harness.Dependency, error) {
 	if orgCfg == nil || len(orgCfg.Agents) == 0 {
+		if path, deps, ok := tryAgentsRepoFallback(ctx, agentName, gitToken, composeOpts, printer); ok {
+			return path, deps, nil
+		}
 		path, err := resolveHarnessPath(fullsendDir, agentName, printer)
 		return path, nil, err
 	}
@@ -2585,6 +2609,9 @@ func resolveAgentSource(ctx context.Context, fullsendDir, agentName string, orgC
 
 	agent := config.LookupMergedAgent(merged, agentName)
 	if agent == nil || !agent.IsConfig {
+		if path, deps, ok := tryAgentsRepoFallback(ctx, agentName, gitToken, composeOpts, printer); ok {
+			return path, deps, nil
+		}
 		path, err := resolveHarnessPath(fullsendDir, agentName, printer)
 		return path, nil, err
 	}
@@ -2611,6 +2638,61 @@ func resolveAgentSource(ctx context.Context, fullsendDir, agentName string, orgC
 	return contained, nil, nil
 }
 
+// tryAgentsRepoFallback attempts to resolve an agent from the default agents
+// repository (fullsend-ai/agents) by fetching the latest harness from the
+// main branch. Returns (path, deps, true) on success, or ("", nil, false)
+// if the fallback should be skipped (offline, no token, agent not found, etc.).
+// All errors are non-fatal — the caller falls through to disk-based lookup.
+func tryAgentsRepoFallback(ctx context.Context, agentName, gitToken string, composeOpts harness.ComposeOpts, printer *ui.Printer) (string, []harness.Dependency, bool) {
+	if !agentsRepoKnownAgents[strings.ToLower(agentName)] {
+		return "", nil, false
+	}
+	if composeOpts.FetchPolicy.Offline {
+		return "", nil, false
+	}
+	if gitToken == "" {
+		return "", nil, false
+	}
+
+	client := gh.New(gitToken)
+	branchSHA, err := client.GetBranchRef(ctx, defaultAgentsRepoOwner, defaultAgentsRepoName, defaultAgentsRepoBranch)
+	if err != nil {
+		printer.StepWarn(fmt.Sprintf("Could not resolve %s/%s@%s: %v", defaultAgentsRepoOwner, defaultAgentsRepoName, defaultAgentsRepoBranch, err))
+		return "", nil, false
+	}
+
+	rawURL := agentsRepoURLPrefix + branchSHA + "/harness/" + agentName + ".yaml"
+
+	content, err := fetch.FetchURL(ctx, rawURL, composeOpts.FetchPolicy)
+	if err != nil {
+		return "", nil, false
+	}
+
+	hash := fetch.ComputeSHA256(content)
+	pinnedURL := rawURL + "#sha256=" + hash
+
+	allowlist := composeOpts.OrgAllowlist
+	if len(allowlist) == 0 {
+		allowlist = config.DefaultAllowedRemoteResources()
+	}
+
+	printer.StepStart(fmt.Sprintf("Fetching agent %s from %s/%s@%s", agentName, defaultAgentsRepoOwner, defaultAgentsRepoName, branchSHA[:12]))
+	localPath, dep, err := harness.FetchAgentHarness(ctx, pinnedURL, harness.ComposeOpts{
+		WorkspaceRoot: composeOpts.WorkspaceRoot,
+		FetchPolicy:   composeOpts.FetchPolicy,
+		AuditLogPath:  composeOpts.AuditLogPath,
+		OrgAllowlist:  allowlist,
+		TreeFetcher:   composeOpts.TreeFetcher,
+		GitToken:      composeOpts.GitToken,
+	})
+	if err != nil {
+		printer.StepWarn(fmt.Sprintf("Agents repo fallback failed for %s: %v", agentName, err))
+		return "", nil, false
+	}
+	printer.StepDone(fmt.Sprintf("Agent %s resolved from %s/%s (latest)", agentName, defaultAgentsRepoOwner, defaultAgentsRepoName))
+	return localPath, []harness.Dependency{dep}, true
+}
+
 // containedLocalPath resolves a relative source path against baseDir and
 // verifies the result stays within baseDir. Returns an error for absolute
 // paths or paths that escape via traversal.

internal/cli/run_test.go

@@ -636,7 +636,7 @@ func TestResolveAgentSource_NoConfig(t *testing.T) {
 	))
 
 	printer := ui.New(io.Discard)
-	path, deps, err := resolveAgentSource(context.Background(), dir, "code", nil, harness.ComposeOpts{}, printer)
+	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)
@@ -659,7 +659,7 @@ func TestResolveAgentSource_ConfigLocalPath(t *testing.T) {
 	}
 
 	printer := ui.New(io.Discard)
-	path, deps, err := resolveAgentSource(context.Background(), dir, "custom", orgCfg, harness.ComposeOpts{}, printer)
+	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)
@@ -677,7 +677,7 @@ func TestResolveAgentSource_ConfigLocalPathNotFound(t *testing.T) {
 	}
 
 	printer := ui.New(io.Discard)
-	_, _, err := resolveAgentSource(context.Background(), dir, "missing", orgCfg, harness.ComposeOpts{}, printer)
+	_, _, err := resolveAgentSource(context.Background(), dir, "missing", "", orgCfg, harness.ComposeOpts{}, printer)
 	require.Error(t, err)
 	assert.Contains(t, err.Error(), "config agent missing")
 }
@@ -693,7 +693,7 @@ func TestResolveAgentSource_ConfigLocalPathAbsoluteRejected(t *testing.T) {
 	}
 
 	printer := ui.New(io.Discard)
-	_, _, err := resolveAgentSource(context.Background(), dir, "evil", orgCfg, harness.ComposeOpts{}, printer)
+	_, _, err := resolveAgentSource(context.Background(), dir, "evil", "", orgCfg, harness.ComposeOpts{}, printer)
 	require.Error(t, err)
 	assert.Contains(t, err.Error(), "absolute paths")
 }
@@ -709,11 +709,60 @@ func TestResolveAgentSource_ConfigLocalPathTraversalRejected(t *testing.T) {
 	}
 
 	printer := ui.New(io.Discard)
-	_, _, err := resolveAgentSource(context.Background(), dir, "passwd", orgCfg, harness.ComposeOpts{}, printer)
+	_, _, err := resolveAgentSource(context.Background(), dir, "passwd", "", orgCfg, harness.ComposeOpts{}, printer)
 	require.Error(t, err)
 	assert.Contains(t, err.Error(), "path traversal")
 }
 
+func TestResolveAgentSource_AgentsRepoFallback_UnknownAgent(t *testing.T) {
+	dir := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "harness"), 0o755))
+
+	printer := ui.New(io.Discard)
+	_, _, err := resolveAgentSource(context.Background(), dir, "nonexistent", "fake-token", nil, harness.ComposeOpts{}, printer)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "harness file not found")
+}
+
+func TestResolveAgentSource_AgentsRepoFallback_Offline(t *testing.T) {
+	dir := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "harness"), 0o755))
+
+	printer := ui.New(io.Discard)
+	opts := harness.ComposeOpts{
+		FetchPolicy: fetch.FetchPolicy{Offline: true},
+	}
+	_, _, err := resolveAgentSource(context.Background(), dir, "triage", "fake-token", nil, opts, printer)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "harness file not found")
+}
+
+func TestResolveAgentSource_AgentsRepoFallback_NoToken(t *testing.T) {
+	dir := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "harness"), 0o755))
+
+	printer := ui.New(io.Discard)
+	_, _, err := resolveAgentSource(context.Background(), dir, "triage", "", nil, harness.ComposeOpts{}, printer)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "harness file not found")
+}
+
+func TestResolveAgentSource_AgentsRepoFallback_DiskWins(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", "triage.yaml"),
+		[]byte("agent: agents/triage.md\nrole: test\n"),
+		0o644,
+	))
+
+	printer := ui.New(io.Discard)
+	path, deps, err := resolveAgentSource(context.Background(), dir, "triage", "", nil, harness.ComposeOpts{}, printer)
+	require.NoError(t, err)
+	assert.Contains(t, path, "triage.yaml")
+	assert.Empty(t, deps)
+}
+
 func TestContainedLocalPath_Valid(t *testing.T) {
 	dir := t.TempDir()
 	require.NoError(t, os.MkdirAll(filepath.Join(dir, "harness"), 0o755))