feat(compose): resolve local profiles and providers in base harness (#5240)

docs/ADRs/0070-portable-provider-profile-resolution.md

@@ -56,26 +56,30 @@ profiles. Today, providers and profiles are an exception.
 
 Extend the harness schema with two new fields:
 
-1. **`openshell.profiles`** — A new list field accepting only HTTPS URLs with `#sha256=...`
-   integrity hashes. Profiles define openshell-level credential type schemas and
-   belong in shared repositories, not locally. No local-path form.
-
-2. **`providers`** — Extend the existing list field to accept both local provider
-   names (existing behavior) and remote HTTPS URLs with `#sha256=...` hashes.
+1. **`openshell.profiles`** — A new list field accepting HTTPS URLs with `#sha256=...`
+   integrity hashes, and local file paths (resolved relative to the harness
+   directory or inherited as absolute cache paths from `base:` composition).
+   Profiles define openshell-level credential type schemas.
+
+2. **`providers`** — Extend the existing list field to accept local provider
+   names (existing behavior), local file paths (resolved relative to the
+   harness directory), and remote HTTPS URLs with `#sha256=...` hashes.
    Mixed forms allowed in the same list.
 
 ### Schema
 
 ```yaml
-# New openshell.profiles field (URL-only)
+# openshell.profiles field (local paths or URLs)
 openshell:
   profiles:
+  - profiles/claude-code.yaml      # Local path (resolved relative to harness)
   - "https://github.com/org/profiles/tree/main/claude-code.yaml#sha256=abc..."
   - "https://github.com/org/profiles/tree/main/google-vertex-ai.yaml#sha256=def..."
 
-# Extended providers field (mixed local names and URLs)
+# Extended providers field (mixed local names, paths, and URLs)
 providers:
-  - "my-local-provider"  # Local name (existing)
+  - "my-local-provider"  # Local name: loaded from providers/my-local-provider.yaml
+  - providers/custom.yaml  # Local path (resolved relative to harness)
   - "https://github.com/org/repo/tree/main/providers/my-provider.yaml#sha256=789..."  # Remote
 ```
 

docs/guides/user/customizing-agents.md

@@ -59,8 +59,9 @@ providers:                       # Inference providers (local names or URLs)
   - vertex                       # Local name: references providers/vertex.yaml
   - "https://github.com/org/repo/tree/main/providers/claude.yaml#sha256=abc..."  # Remote URL
 
-openshell:                       # Openshell provider profiles (URL-only, with integrity hash)
+openshell:                       # Openshell provider profiles (local paths or URLs)
   profiles:
+    - profiles/claude-code.yaml    # Local path: resolved relative to harness
     - "https://github.com/org/profiles/tree/main/claude-code.yaml#sha256=def..."
 
 validation_loop:                     # script is required; these sub-fields are optional
@@ -116,11 +117,12 @@ providers:
   - "https://github.com/org/repo/tree/main/providers/claude.yaml#sha256=abc..."  # Remote
 ```
 
-**`openshell.profiles`** accepts only HTTPS URLs (profiles are always remote):
+**`openshell.profiles`** accepts local paths and HTTPS URLs:
 
 ```yaml
 openshell:
   profiles:
+    - profiles/claude-code.yaml    # Local path (resolved relative to harness)
     - "https://github.com/org/profiles/tree/main/claude-code.yaml#sha256=abc..."
 ```
 

internal/cli/lock.go

@@ -779,17 +779,29 @@ func resolveFromLock(h *harness.Harness, entry *lock.HarnessLock, workspaceRoot
 	}
 	h.Skills = filtered
 
-	// Strip URL entries from providers — URL-resolved providers are now in
-	// the ResolvedProvider list, mirroring resolve.ResolveHarness behavior.
+	// Strip URL and absolute-path entries from providers — URL-resolved
+	// providers are in the ResolvedProvider list, and absolute-path entries
+	// (from base composition cache) will be resolved by the local-only
+	// ResolveHarness pass. Keep only bare provider names.
 	remainingProviders := h.Providers[:0]
 	for _, p := range h.Providers {
-		if !harness.IsURL(p) {
+		if !harness.IsURL(p) && !harness.IsProviderPath(p) {
 			remainingProviders = append(remainingProviders, p)
 		}
 	}
 	h.Providers = remainingProviders
+	// Strip URL and absolute-path profiles — URL-resolved profiles are in
+	// the ResolvedProfile list from lock deps, and absolute-path entries
+	// (from base composition cache) are reconstructed from lock deps too.
+	// Keep only relative-path profiles for the local-only ResolveHarness pass.
 	if h.OpenShell != nil {
-		h.OpenShell.Profiles = nil
+		remaining := h.OpenShell.Profiles[:0]
+		for _, p := range h.OpenShell.Profiles {
+			if !harness.IsURL(p) && !filepath.IsAbs(p) {
+				remaining = append(remaining, p)
+			}
+		}
+		h.OpenShell.Profiles = remaining
 	}
 
 	return resolve.ResolveResult{

internal/cli/run.go

@@ -478,6 +478,29 @@ func runAgent(ctx context.Context, agentName, fullsendDir, outputBase, targetRep
 		}
 	}
 
+	// When profiles or providers use local paths (from ResolveRelativeTo or
+	// base composition), ResolveHarness must still run to parse them into
+	// ResolvedProfile/ResolvedProvider — even without URL references.
+	// The lock-file and URL-resolution paths strip entries they consume;
+	// this pass handles whatever remains. Outputs are merged and deduped.
+	if len(h.OpenShellProfiles()) > 0 || hasLocalProviders(h) {
+		prev := result
+		var resolveErr error
+		result, resolveErr = resolve.ResolveHarness(ctx, h, resolve.ResolveOpts{
+			WorkspaceRoot: absFullsendDir,
+		})
+		if resolveErr != nil {
+			return fmt.Errorf("resolving local profiles/providers: %w", resolveErr)
+		}
+		result.Deps = append(prev.Deps, result.Deps...)
+		result.Profiles = append(prev.Profiles, result.Profiles...)
+		result.Providers = append(prev.Providers, result.Providers...)
+		result.Warnings = append(prev.Warnings, result.Warnings...)
+	}
+	for _, w := range result.Warnings {
+		printer.StepWarn(w)
+	}
+
 	if resolved, overridden := applySandboxImageOverride(h.Image); overridden {
 		printer.StepInfo(fmt.Sprintf("Image override via FULLSEND_SANDBOX_IMAGE: %s -> %s", h.Image, resolved))
 		h.Image = resolved
@@ -3174,6 +3197,15 @@ func mergeProviderDefs(localDefs []harness.ProviderDef, urlProviders []resolve.R
 	return allDefs, shadowed
 }
 
+func hasLocalProviders(h *harness.Harness) bool {
+	for _, p := range h.Providers {
+		if !harness.IsURL(p) && harness.IsProviderPath(p) {
+			return true
+		}
+	}
+	return false
+}
+
 // sandboxProviderNames returns the provider names that should be attached to
 // the sandbox: harness-declared (local) names plus URL-resolved names.
 // Directory providers not declared in the harness are excluded — they may

internal/harness/compose.go

@@ -127,6 +127,18 @@ func LoadWithBase(ctx context.Context, path string, opts ComposeOpts) (*Harness,
 				return nil, nil, fmt.Errorf("resolving URL-sourced host_files: %w", err)
 			}
 			deps = append(deps, hostFileDeps...)
+
+			profileDeps, err := resolveBaseProfiles(ctx, child, opts.SourceURL, opts.OrgAllowlist, opts)
+			if err != nil {
+				return nil, nil, fmt.Errorf("resolving URL-sourced profiles: %w", err)
+			}
+			deps = append(deps, profileDeps...)
+
+			providerDeps, err := resolveBaseProviders(ctx, child, opts.SourceURL, opts.OrgAllowlist, opts)
+			if err != nil {
+				return nil, nil, fmt.Errorf("resolving URL-sourced providers: %w", err)
+			}
+			deps = append(deps, providerDeps...)
 		}
 
 		if err := child.validateForge(); err != nil {
@@ -260,6 +272,18 @@ func loadBaseChain(
 		}
 		deps = append(deps, hostFileDeps...)
 
+		profileDeps, err := resolveBaseProfiles(ctx, base, baseRef, allowlist, opts)
+		if err != nil {
+			return nil, nil, fmt.Errorf("resolving base profiles from %s: %w", cleanURL, err)
+		}
+		deps = append(deps, profileDeps...)
+
+		providerDeps, err := resolveBaseProviders(ctx, base, baseRef, allowlist, opts)
+		if err != nil {
+			return nil, nil, fmt.Errorf("resolving base providers from %s: %w", cleanURL, err)
+		}
+		deps = append(deps, providerDeps...)
+
 		baseDir = childDir
 	} else {
 		// Local path base
@@ -774,6 +798,82 @@ func resolveBaseHostFiles(ctx context.Context, base *Harness, baseURL string, al
 	return deps, nil
 }
 
+// resolveBaseProfiles fetches profile files with relative paths from a
+// URL-referenced base harness. For each openshell.profiles entry that is a
+// non-empty relative path (not a URL or absolute path), the file is fetched
+// from the base URL's directory, cached content-addressed, and the entry is
+// rewritten to the local cache path. This matches the resolution behavior
+// for agent, policy, skills, scripts, and host_files in base composition.
+func resolveBaseProfiles(ctx context.Context, base *Harness, baseURL string, allowlist []string, opts ComposeOpts) ([]Dependency, error) {
+	if base.OpenShell == nil || len(base.OpenShell.Profiles) == 0 {
+		return nil, nil
+	}
+
+	baseURLDir := urlParentDirPrefix(baseURL)
+	if baseURLDir == "" {
+		return nil, fmt.Errorf("cannot determine directory from base URL")
+	}
+
+	var deps []Dependency
+
+	for i, p := range base.OpenShell.Profiles {
+		if p == "" || IsURL(p) || filepath.IsAbs(p) {
+			continue
+		}
+		fieldName := fmt.Sprintf("openshell.profiles[%d]", i)
+		if err := validateBaseRelPath(fieldName, p); err != nil {
+			return nil, err
+		}
+		dep, cachePath, err := fetchBaseFile(ctx, fieldName, baseURLDir, p, allowlist, opts, "resource", false)
+		if err != nil {
+			return nil, err
+		}
+		base.OpenShell.Profiles[i] = cachePath
+		deps = append(deps, dep)
+	}
+
+	return deps, nil
+}
+
+// resolveBaseProviders fetches provider files with relative paths from a
+// URL-referenced base harness. For each providers entry that is a non-empty
+// relative path (not a URL, absolute path, or bare provider name), the file
+// is fetched from the base URL's directory, cached content-addressed, and
+// the entry is rewritten to the local cache path.
+func resolveBaseProviders(ctx context.Context, base *Harness, baseURL string, allowlist []string, opts ComposeOpts) ([]Dependency, error) {
+	if len(base.Providers) == 0 {
+		return nil, nil
+	}
+
+	baseURLDir := urlParentDirPrefix(baseURL)
+	if baseURLDir == "" {
+		return nil, fmt.Errorf("cannot determine directory from base URL")
+	}
+
+	var deps []Dependency
+
+	for i, p := range base.Providers {
+		if p == "" || IsURL(p) || filepath.IsAbs(p) {
+			continue
+		}
+		if !IsProviderPath(p) {
+			continue
+		}
+		fieldName := fmt.Sprintf("providers[%d]", i)
+		if err := validateBaseRelPath(fieldName, p); err != nil {
+			return nil, err
+		}
+		dep, cachePath, err := fetchBaseFile(ctx, fieldName, baseURLDir, p, allowlist, opts, "resource", false)
+		if err != nil {
+			return nil, err
+		}
+		base.Providers[i] = cachePath
+		deps = append(deps, dep)
+	}
+
+	return deps, nil
+}
+
 // validateBaseRelPath validates that a relative path inherited from a URL base
 // is safe to resolve. Rejects null bytes, query/fragment markers, URLs,
 // absolute paths, and path traversal segments.